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Chapter 1 


Certificate Manager API 


1.1 References 


[1] Software Architecture Document, Version 1.1 Revision 1.4, LiMo Foundation, 11 September 2007 


1.2 Overview 


The Certificate Manager implements the administration and processing of security certificates for a partic- 
ular system. The main services supplied by the certificate are: 


e Certificate Processing (parsing, verification etc). 
e Certificate Storage. 

e Certificate Meta data administration. 

e Certificate Revocation discovery. 

e Limited cryptographic services. 


e Digital signature processing. 


1.2.1 Certificate Manager Architecture 


The Certificate Manager services are split into Foundation and Framework sections. The Foundation con- 
sists of a set of plug-in modules which implement the services listed above. The Framework is used to 
implement common services and the routing and control of service requests to the plug-in modules. 


The following plug-ins have been defined: 


e Cryptography Plug-in 

e Certificate Processing Plug-in 

e Digital Signature Plug-in 

e Certificate Revocation Status Plug-in 


e Certificate Store Plug-in 


2 Certificate Manager API 


Applications/Services 


Certificate Manager 


Certificate a 
Metadata Certificate 


Management 


Figure 1.1: Certificate Manager Architecture Diagram 


Each plug-in is a separate Linux shared object. The actual shared object that implements a plug-in is 
specified in the Certificate Manager configuration file. When the Certificate Manager requires access to a 
particular plug-in, it will search the configuration file for the appropriate entry. Once found, the Certificate 
Manager will load the shared object and call the required API functions. For the Certificate Processing and 
Certificate Store plug-ins, multiple instances can be defined for use at the same time. This allows extra 
functionality to be added easily. For example, there may be an existing Certificate Processing plug-in that 
understands X.509 certificates. If WTLS certificates are also required, a new shared object (conforming 
to the Certificate Processing Framework API) can be written. This shared object can be added to the 
platform installation and the Certificate Manager configuration updated. There will now be two Certificate 
Processing plug-ins listed in the configuration file: one for X.509 and one for WTLS. The Certificate 
Manager can use either plug-in when attempting to process a certificate. 
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1.2.2 Certificate Verification Diagram 
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Figure 1.2: Example Sequence Diagram for Cert fiti evento itkor)1:01:00 2008 by Doxygen 


1.3 Industry Standard 


1.3 Industry Standard 


None 


1.4 External API Documents 


None 


1.5 Plug-in Extension Point Interface 


None 


1.6 Other Interfaces 


None 


1.7 Other Notes 


None 
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Data Structure Index 


2.1 Data Structures 


Here are the data structures with brief descriptions: 
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Data Structure Index 
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Chapter 3 


File Index 


3.1 File List 


Here is a list of all documented files with brief descriptions: 


CertMgr.h (This is the header file for the LiMo Certificate Manager Foundation API) ...... 
CertMgrCertProcessing.h (This file specifies the certificate-processing plug in component for 
certificate manager. This plug in is responsible for verifying and parsing of certificates ) 
CertMgrCryptography.h (This file specifies the crypto graphic services supplied by the crypto- 
graphic plug in component for the certificate manager) ................. 
CertMgrDebug.h (This is the header file for the LiMo Certificate Manager Foundation API ) 
CertMgrInternal.h (This is the header file for the LiMo Certificate Manager Foundation API) . . 
CertMgrPlugin.h (This is the header file for LiMo Certificate Manager Plug-in framework API ) 
CertMgrRevocationStatus.h (This file specifies the revocation status plug in componenet for cer- 
tificate manager. This plug in is responsible for handling certificate status request ) 
CertMgrSignature.h (This is the component which implements digital signature capability for the 
Certificate Manager)... enn n n knn 
CertMgrStore.h (This file specifies the storage services supplied by the certificate store plug-in 
component for the certificate manager) ......... o... . e... . +... noun 
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Data Structure Documentation 


4.1 _CertMgrCertLinkedList Struct Reference 


#include <CertMgr.h> 


4.1.1 Detailed Description 


Linked list of certificates. This is the structure, which represents a member of the linked list of certificates. 


Data Fields 


e CertMgrMemBuff x certificate 
e CertMgrCertLinkedList * next 


4.1.2 Field Documentation 
4.1.2.1 CertMgrMemBuffx CertMgrCertLinkedList::certificate 


certificate data in buffer descriptor 


4.1.2.2 struct _CertMgrCertLinkedList* CertMgrCertLinkedList::next 


end of list indicated by null value in next 


The documentation for this struct was generated from the following file: 


e CertMgr.h 


12 Data Structure Documentation 


4.2 CertMgrAdditionalFields Struct Reference 


#include <CertMgr.h> 


4.2.1 Detailed Description 


some additional fields 


Data Fields 


e UINT32 numberOfFields 
e CertMgrCertFieldDesc * fields 


4.2.2 Field Documentation 
4.2.2.1 UINT32 CertMgrAdditionalFields::numberOfFields 


the number of fields in the field array 


4.2.2.2 CertMgrCertFieldDescx CertMgrA dditionalFields: :fields 


an array of field descriptors 


The documentation for this struct was generated from the following file: 


e CertMgr.h 
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4.3 CertMgrCertDescriptor Struct Reference 


#include <CertMgr.h> 


4.3.1 Detailed Description 


parsed certificate content 


Data Fields 


e char x type 
e CertMgrMandatoryFields mandatory 
e CertMgrAdditionalFields additional 


4.3.2 Field Documentation 
4.3.2.1 charx CertMgrCertDescriptor::type 


the certificate type identifier 


The documentation for this struct was generated from the following file: 


e CertMgr.h 
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4.4 CertMgrCertFieldDesc Struct Reference 


#include <CertMgr.h> 


4.4.1 Detailed Description 


a generic structure to define a field in a certificate 


Data Fields 


e CertMgrCertField name 
e void + data 
e UINT32 dataSize 


4.4.2 Field Documentation 
4.4.2.1 CertMgrCertField CertMgrCertFieldDesc::name 


the name of the certificate field 


4.4.2.2 void» CertMgrCertFieldDesc::data 


the address of the field data 


4.4.2.3 UINT32 CertMgrCertFieldDesc::dataSize 


the size of the field data 


The documentation for this struct was generated from the following file: 


e CertMgr.h 
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4.5 CertMgrCertld Struct Reference 


#include <CertMgr.h> 


4.5.1 Detailed Description 


The certificate id determined by the API 


Data Fields 


e CertMgrStorageld storeld 
e UINT32 certificateNo 
e char x type 


4.5.2 Field Documentation 
4.5.2.1 CertMgrStorageld CertMgrCertld::storeld 


an identifying string for a certificate store 


4.5.2.2 UINT32 CertMgrCertld::certificateNo 


a number identifying a certificate in the store it is stored in 


4.5.2.3 charx CertMgrCertlId::type 


the certificate type 


The documentation for this struct was generated from the following file: 


e CertMgr.h 
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4.6 CertMerCtx Struct Reference 


#include «CertMgr.h» 


4.6.1 Detailed Description 


The context record used to store certificate retrieval context, to be used by successive calls to retrieve 
certificates 


Data Fields 


e BOOL open 

BOOL firstCall 

BOOL lastRetrieved 

BOOL retrieveByField 
CertMgrCertFieldDesc searchTarget 
BOOL retrieveByType 

char * type 

UINT32 lastRetrievedId 
CertMgrStorageld storeld 


4.6.2 Field Documentation 
4.6.2.1 BOOL CertMgrCtx::open 


1f TRUE, indicates that the store is open, and certificates can be retrieved 


4.6.2.2 BOOL CertMgrCtx::firstCall 


if TRUE, indicates that this is the first call in a sequence of retrieval calls 


4.6.2.3 BOOL CertMgrCtx::lastRetrieved 


if TRUE, indicates that the last certificate has been retrieved from store in this retrieval sequence 


4.6.2.4 BOOL CertMgrCtx::retrieveByField 


if TRUE, indicates that we are retrieving based on a certificate field (name, subject, etc...) 


4.6.2.5 CertMgrCertFieldDesc CertMgrCtx::searchTarget 


1f retrieval is by field, this specifies which field we are looking for 


4.6.2.6 BOOL CertMgrCtx::retrieveBy Type 


1f TRUE, indicates that we are retrieving based on certificate type 
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4.6.2.7 charx CertMgrCtx::type 


if retrieving by type, this specifies the certificate type to look for 


4.6.2.8 UINT32 CertMgrCtx::lastRetrievedld 


the certificate id of the last retrieved certificate (0 if none retrieved) 


The documentation for this struct was generated from the following file: 


e CertMgr.h 
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4.7 CertMgrFilBuff Struct Reference 


#include <CertMgr.h> 


4.7.1 Detailed Description 


File data descriptor specifying a file (path-name), an offset from start of file to the first byte of the file 
record and the size of the file data record in the file 


Data Fields 


e char x fileName 
e UINT32 fileOffset 
e UINT32 size 


4.7.2 Field Documentation 
4.7.2.1 charx CertMgrFilBuff::fileName 


path-name of file 


4.7.2.2 UINT32 CertMgrFilBuff: :fileOffset 


offset of record from start of file 


4.7.2.3 UINT32 CertMgrFilBuff::size 


size of record on file 


The documentation for this struct was generated from the following file: 


e CertMgr.h 
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4.8 CertMgrKeyDescr Struct Reference 


#include <CertMgr.h> 


4.8.1 Detailed Description 


A key descriptor structure, specifying the key data and size contained inside a memory buffer 


Data Fields 


e CertMgrMemBuff + key 


4.8.2 Field Documentation 
4.8.2.1 CertMgrMemBuff« CertMgrKeyDescr::key 


key data 


The documentation for this struct was generated from the following file: 


e CertMgr.h 
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4.9 CertMgrMandatoryFields Struct Reference 


#include <CertMgr.h> 


4.9.1 Detailed Description 


the certificate descriptor in decoded form. 


Data Fields 


e CertMgrSigAlgoFldData sigAlgo 

e CertMerlssuerFldData issuer 

e CertMgrValidityFldData validPeriod 
e CertMgrSubjectFldData subject 


The documentation for this struct was generated from the following file: 


e CertMgr.h 
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4.10  CertMgrMemBuff Struct Reference 


#include <CertMgr.h> 


4.10.1 Detailed Description 


Memory buffer descriptor for a pointer to an array, containing unsigned 8 bit data elements. 


Data Fields 


e UINTS x data 
e UINT32 size 
e UINT32 firstFree 


4.10.2 Field Documentation 
4.10.2.1 UINT8x CertMgrMemBuff::data 


address of the first buffer location in memory 


4.10.2.2 UINT32 CertMgrMemBuff::size 


size of the allocated buffer 


4.10.2.3 UINT32 CertMgrMemBuff::firstFree 


starting offset in data buffer available for appending new data 


The documentation for this struct was generated from the following file: 


e CertMgr.h 
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4.11 CertMgrMetaDatald Struct Reference 


#include <CertMgr.h> 


4.11.1 Detailed Description 


meta data specification 


Data Fields 


e char x metaDataType 
e char x ownerApplication 


4.11.2 Field Documentation 
4.11.2.1 char» CertMgrMetaDatald::metaDataType 


a null terminated string, identifying the type 


4.11.2.2 chars CertMgrMetaDatald::ownerApplication 


a null terminated string, identifying the application which created the type 


The documentation for this struct was generated from the following file: 


e CertMgr.h 
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4.12 CertMgrPlugInDescr Struct Reference 


#include <CertMgrSignature.h> 


4.12.1 Detailed Description 


A cryptor plug-in descriptor used to determine which plug-in supports which algorithm. 


Data Fields 


e CertMgrCipherAlgo algorithm 
e char x plugInLocation 


4.12.2 Field Documentation 
4.12.2.1 CertMgrCipherAlgo CertMgrPlugInDescr::algorithm 


the algorithm supported 


4.12.2.2 charx CertMgrPlugInDescr::plugInLocation 


the path to the plug-in 


The documentation for this struct was generated from the following file: 


e CertMgrSignature.h 
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4.13 CertMgrValidityFldData Struct Reference 


#include <CertMgr.h> 


4.13.1 Detailed Description 


definition for valid period field data 


Data Fields 


UINT32 firstSecond 
UINT32 firstHour 
UINT32 firstDay 
UINT32 firstMonth 
UINT32 first Year 

e UINT32 lastSecond 
UINT32 lastHour 
UINT32 lastDay 
UINT32 lastMonth 
UINT32 lastYear 


The documentation for this struct was generated from the following file: 


e CertMgr.h 
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File Documentation 


5.1 CertMgr.h File Reference 


5.1.1 Detailed Description 


This is the header file for the LiMo Certificate Manager Foundation API. 


Data Structures 


struct CertMgrValidityFldData 
struct CertMgrMemBuff 

struct CertMgrFilBuff 

struct CertMgrCertFieldDesc 
struct CertMgrCtx 

struct CertMgrMandatory Fields 
struct CertMgrAdditionalFields 
struct CertMgrCertDescriptor 
struct CertMgrCertld 

struct CertMgrMetaDatald 
struct _CertMgrCertLinkedList 
struct CertMgrKeyDescr 


Defines 


e #define MAX ERRCODES PER COMPONENT ((INT32)255) 


number of error codes reserved for each component 


e #define MAX RESERVED ERR CODE ((INT32)-255) 


first error code available the certificate manager sub system 


e #define CERTMGR START ERRCODE ( (INT32(MAX_RESERVED_ERR_CODE - (0 x 
MAX ERRCODES PER COMPONENT))) 


first error code available to the certificate manager foundation module 
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#define CERTPROCESS START ERRCODE ( (INT32(MAX RESERVED ERR CODE - (1 x 
MAX ERRCODES PER COMPONENT))) 


first error code available to the processing framework module 


#define CERTCRYPTO START ERRCODE ( (INT32XMAX RESERVED ERR CODE - (2 x 
MAX ERRCODES PER COMPONENT))) 


first error code available to the crypto graphic framework module 


#define CERTSIGNATURE START ERRCODE ( (INT32)(MAX_RESERVED_ERR_CODE - (3 
* MAX ERRCODES PER COMPONENT))) 


first error code available to the signature framework module 


#define CERTMETADATA START ERRCODE ( (INT32)(MAX_RESERVED_ERR_CODE - (4 x 
MAX ERRCODES PER COMPONENT))) 


first error code available to the meta data framework module 


#define CERTREVOC STATUS START ERRCODE ( (INT32XMAX RESERVED ERR CODE 
- (5 x MAX ERRCODES PER COMPONENT))) 


first error code available to the revocation status framework module 


#define CERTSTORE_START_ERRCODE ( (INT32(MAX_RESERVED_ERR_CODE - (6 x 
MAX_ERRCODES_PER_COMPONEND)) ) 


first error code available to the certificate store framework module 


#define TRUE ((int)1) 
#define FALSE ((TRUE)) 
#define ERR UNKNOWN RESULT CODE ( INT32XCERTMGR START ERRCODE - 0) ) 


function return error code indicating the result code was unknown 


#define ERR_BROKEN_EXTERN_CHAIN ( INT32XCERTMGR START ERRCODE - 1) ) 


function return error code indicating the specified certificates could not be arranged into a certificate chain 


#define ERR_NO_ROOT_CERTIFICATE ( (INT32)(CERTMGR_START_ERRCODE - 2) ) 


function return error code indicating a root certificate did not exist 


#define ERR_INVALID_SIGNATURE ( INT32XCERTMGR START ERRCODE - 3) ) 


function return error code indicating an invalid signature 


#define ERR_INVALID_CERTIFICATE ((1INT32(CERTMGR_START_ERRCODE - 4) ) 


function return error code indicating an invalid certificate 


#define ERR FILE IO ERROR ( INT32XCERTMGR START ERRCODE - 5) ) 


function return error code indicating a file input/output error occurred 


#define ERR UNSUPPORTED HASH TYPE ( (INT32)(CERTMGR_START_ERRCODE - 6) ) 


function return error code indicating the specified hash type is not supported 


#define ERR_UNSUPPORTED_KEY_TYPE ( (INT32)(CERTMGR_START_ERRCODE - 7) ) 


function return error code indicating the specified key type is not supported 
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e #define ERR_UNSUPPORTED_OPERATION ( (INT32)(CERTMGR_START_ERRCODE - 8) ) 


function return error code indicating the specified operation is not supported 


#define ERR_STORE_IS_FULL ( INT32XCERTMGR START ERRCODE - 9) ) 


function return error code indicating no storage space is available 


#define ERR_INVALID_CERT_ID ( INT32CERTMGR START ERRCODE - 10) ) 


function return error code indicating the specified certificate does not exist 


#define ERR_BUFFER_TOO_SMALL ( (INT32XCERTMGR START ERRCODE - 11) ) 


function return error code indicating the specified buffer is too small 


#define ERR STORE IS EMPTY ( INT32)(CERTMGR START ERRCODE - 12) ) 


function return error code indicating the store is empty 


#define ERR NO MORE CERTIFICATES ( INT32(CERTMGR START ERRCODE - 13) ) 


function return error code indicating there are no more certificates to be retrieved 


#define ERR STORE IS UNAVAILABLE ( (INT32)(CERTMGR_START_ERRCODE - 14) ) 


function return error code indicating the specified store is not available 


#define ERR DUPLICATE CERTIFICATE ( (INT32)(CERTMGR_START_ERRCODE - 15) ) 


function return error code indicating a duplicate certificate exists already 


#define CERTMGR_HASH_MD2_RSA "md2WithRSAEncryption" 
a signature based on MD2 encrypted with RSA - naming is based on ASN.1 TAG names (see RFC3279) 


#define CERTMGR HASH MD35 RSA "md5WithRSAEncryption" 
a signature based on MD5 encrypted with RSA - naming is based on ASN.1 TAG names (see RFC3279) 


#define CERTMGR_HASH_SHA1_RSA "sha-1WithRSAEncryption" 
a signature based on SHA] encrypted with RSA - naming is based on ASN.1 TAG names (see RFC3279) 


#define CERTMGR CIPHER RSA "RSA" 
cipher algorithm based on RSA 


#define CERTMGR CERTFLD VERSION "version" 


a certificate field name specification for the version field 


#define CERTMGR CERTFLD SERIALNO "serial number" 


a certificate field name specification for the serial number field 


#define CERTMGR CERTFLD SIG ALGO "signing algorithm" 


a certificate field name specification for the signature algorithm field 


#define CERTMGR CERTFLD ISSUER "issuer" 


a certificate field name specification for the issuer field 


#define CERTMGR CERTFLD VALIDITY "valid period" 
a certificate field name specification for the end of validity field 
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#define CERTMGR CERTFLD SUBJECT "subject" 


a certificate field name specification for the subject field 


#define CERTMGR CERTFLD PUBLIC KEY "public key" 
a certificate field name specification for the public key field 


#define CERTMGR CERTFLD ISSUER UID "issuer UID" 


a certificate field name specification for the issuer UID field 


#define CERTMGR CERTFLD SUBJECT UID "subject UID" 
a certificate field name specification for the subject UID field 


#define CERTMGR CERTFLD EXTENSIONS "extensions" 


a certificate field name specification for the extensions field 


#define CERTMGR CERTFLD SIGNED DATA "certificate information" 


a certificate field name specification for the certificate information field 


#define CERTMGR CERTFLD SIGNATURE "certificate signature" 


a certificate field name specification for the certificate signature field 


#define CERTMGR CERTID HASH SIZE 16 


the size of the hash identifying each certificate under the control of the certificate manager 


#define CERTMGR INIT CONTEXT(context, size) memset((voidx)context, 0, size); 


Typedefs 


e typedef unsigned char UINT8 


definition for unsigned 8 bit integer 


typedef char INT8 


definition for signed 8 bit integer 


typedef unsigned int UINT16 


definition for unsigned 16 bit integer 


typedef int INT16 


definition for signed 16 bit integer 


typedef unsigned long int UINT32 


definition for unsigned 32 bit integer 


typedef long int INT32 
definition for signed 32 bit integer 


typedef int BOOL 
typedef INT32 CertMgrResult 
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typedef char * CertMgrVersionFldData 


definition for version field data 


typedef char x CertMgrSerialNoFldData 


definition for serial number field data 


typedef char * CertMgrSigAlgoFldData 


definition for signature algorithm field data 


typedef char x CertMgrIssuerFldData 


definition for issuer field data 


typedef char * CertMgrSubjectFldData 
definition for subject field data 


typedef char * CertMgrPublicKeyFldData 
definition for public key field data 


typedef char x CertMgrIssuerUIDFldData 
definition for issuer UID field data 


typedef char x CertMgrSubject UIDFldData 
definition for subject UID field data 


typedef char * CertMgrExtensionsFldData 


definition for extensions field data 


typedef char * CertMgrSigType 


definition for the signature hash/key combination 


typedef char * CertMgrCipherAlgo 


definition for cipher algorithms 


typedef char x CertMgrStorageld 


definition for the supported certificate store types 


typedef char * CertMgrCertStatus 


definition for the certificate status 


typedef char * CertMgrCertField 


definition for a certificate field identifier 


typedef _CertMgrCertLinkedList CertMgrCertLinkedList 


Functions 


CertMgrResult CertMgrErrorCodeToMessage (CertMgrResult code, char **resultMessage) 


maps the specified error code to an error message String. 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 


30 


File Documentation 


CertMgrResult CertMgrGetCertificate Type (CertMgrMemBuff «certificate, char xcertificateType) 


Determines the type of the certificate. 


CertMgrResult CertMgrVerifyCertificate (CertMgrCertLinkedList *certificateList) 


Verifies a certificate chain, consisting of one or more certificates. 


CertMgrResult CertMgrVerifyMBufSigWithCert (char «certificateType, CertMgrMemBuff 
xcertificate, CertMgrMemBuff «message, CertMgrMemBuff *signature) 


Uses a security certificate to verify that the specified signature matches a specified message stored in memory 
The certificate determines the signature algorithm and the public key to decode the signature. 


CertMgrResult CertMgrVerifyFBufSigWithCert (char  xcertificateType, CertMgrMemBuff 
«certificate, CertMgrFilBuff «msglnFile, CertMgrMemBuff «signature) 


Uses a security certificate to verify that a specified signature matches the specified message stored in a file 
record. The certificate determines the signature algorithm and the public key to decode the signature. 


CertMgrResult CertMgrVerifyMemBufferSignature (CertMgrSigType algorithm, CertMgrKeyDescr 
*keyDescriptor, CertMgrMemBuff «message, CertMgrMemBuff *signature) 


Uses a hash type specification and a key descriptor to verify that a specified signature matches the specified 
message stored in a memory buffer. 


CertMgrResult CertMgrVerifyFileBufferSignature (CertMgrSigType algorithm, CertMgrKeyDescr 
*keyDescriptor, CertMerFilBuff «msgInFile, CertMgrMemBuff xsignature) 


Uses a hash type specification and a key descriptor to verify that a specified signature matches the specified 
message stored in a file record. 


CertMgrResult CertMgrGenerateMemBuffSignature (CertMgrSigType algorithm, void xkeyld, 
CertMgrMemBuff «message, CertMgrMemBuff xsignature) 


this function will generate a signature over a specified memory buffer. 


CertMgrResult CertMgrGenerateFilBuffSignature (CertMgrSigType algorithm, void xkeyld, Cert- 
MgrFilBuff *msgInFile, CertMgrMemBuff *signature) 


this function will generate a signature over a specified file record. 


CertMgrResult CertMgrAddMetaDataToCert (CertMgrCertld xcertificateld, CertMgrMetaDatald 
+metaDatald, CertMgrMemBuff x*metaData) 


saves the specified meta data block in the meta data buffer and links the data to a certificate with the 
specified id. 


CertMgrResult CertMgrRemoveMetaDataFromCert (CertMgrCertld xcertificateld, CertMgrMeta- 
Datald «metaDatald) 


removes specified meta data from the meta data buffer and unlinks the specified certificate from the removed 
meta data. 


CertMgrResult CertMgrPurgeMetaDataFromCert (CertMgrCertld «certificateld) 


removes all meta associated with the specified certificate. 


CertMgrResult CertMgrRetrieveMetaDataForCert (CertMgrCertld x*certificateld, CertMgrMeta- 
Datald xmetaDatald, CertMgrMemBuff xmetaData) 


retrieves the specified meta data type from the meta data buffer. 
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CertMgrResult CertMgrExtractCertificateData (CertMgrMemBuff xcertificate, CertMgrCert- 
Descriptor «certificateDescriptor) 


Assemble a certificate record from raw certificate data. 


CertMgrResult CertMgrReleaseCertificateData (CertMgrCertDescriptor «certificateDescriptor) 


Releases certificate field records allocated in a previous call to CertMgrExtractCertificate Data. 


CertMgrResult CertMgrEnableCertificate (CertMgrCertld x*certificateld) 


This function will change the state of the specified certificate to enabled. 


CertMgrResult CertMgrDisableCertificate (CertMgrCertld xcertificateld) 


This function will change the state of the specified certificate to disabled. 


CertMgrResult CertMgrRetrieveCertStatus (CertMgrCertld «certificateld, CertMgrCertStatus 
xstatus) 


This function is used to retrieve the certificate status (whether it is enabled or disabled). 


CertMgrResult CertMgrAddCertificateToStore (CertMgrMemBuff «certificate, CertMgrCertld 
xcertificateld, CertMgrStorageld storeld) 


This function is used to store the certificate memory buffer in the specified store. 


CertMgrResult CertMgrRemoveCertificateFromStore (CertMgrCertld xcertificateld) 


This function is used to remove the specified certificate from the specified store. 


CertMgrResult  CertM grRetrieveCertFromStore (CertMgrCtx context, CertMgrMemBuff 
«certificate, CertMgrCertld xcertificateld) 


This function is used to retrieve one or more certificates from the certificate store. 
In the first call the context must be properly initialized. 


5.1.2 Define Documentation 


5.1.2.1 #define CERTCRYPTO_START_ERRCODE ((INT32(MAX_RESERVED_ERR_CODE 
- (2 x MAX ERRCODES PER COMPONENT))) 


first error code available to the crypto graphic framework module 


5.1.2.2 #define CERTMETADATA START ERRCODE ( (INT32)(MAX_- 
RESERVED ERR CODE - (4 x MAX ERRCODES PER COMPONENT)) 
) 


first error code available to the meta data framework module 


5.1.2.3 #define CERTMGR CERTFLD EXTENSIONS "extensions" 


a certificate field name specification for the extensions field 


5.1.2.4 #define CERTMGR CERTFLD ISSUER "issuer" 


a certificate field name specification for the issuer field 
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5.1.2.5 #define CERTMGR CERTFLD ISSUER UID "issuer UID" 


a certificate field name specification for the issuer UID field 


5.1.2.6 #define CERTMGR CERTFLD PUBLIC KEY "public key" 


a certificate field name specification for the public key field 


5.1.2.7 #define CERTMGR CERTFLD SERIALNO "serial number" 


a certificate field name specification for the serial number field 


5.1.2.8 #define CERTMGR CERTFLD SIG ALGO "signing algorithm" 


a certificate field name specification for the signature algorithm field 


5.1.2.9 #define CERTMGR CERTFLD SIGNATURE "certificate signature" 


a certificate field name specification for the certificate signature field 


5.1.2.10 #define CERTMGR CERTFLD SIGNED DATA "certificate information" 


a certificate field name specification for the certificate information field 


5.1.2.11 #define CERTMGR CERTFLD SUBJECT "subject" 


a certificate field name specification for the subject field 


5.1.2.12 #define CERTMGR CERTFLD SUBJECT UID "subject UID" 


a certificate field name specification for the subject UID field 


5.1.2.13 #define CERTMGR CERTFLD VALIDITY "valid period" 


a certificate field name specification for the end of validity field 


5.1.2.14 #define CERTMGR CERTFLD VERSION "version" 


a certificate field name specification for the version field 


5.1.2.15 #define CERTMGR CERTID HASH SIZE 16 


the size of the hash identifying each certificate under the control of the certificate manager 
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5.1.2.16 #define CERTMGR CIPHER RSA "RSA" 


cipher algorithm based on RSA 


5.1.2.17 #define CERTMGR HASH MD2 RSA "md2WithRSA Encryption" 


a signature based on MD2 encrypted with RSA - naming is based on ASN.1 TAG names (see RFC3279) 


5.1.2.18 #define CERTMGR HASH MD5 RSA "md5WithRSA Encryption" 


a signature based on MDS encrypted with RSA - naming is based on ASN.1 TAG names (see RFC3279) 


5.1.2.19 #define CERTMGR HASH _SHA1 RSA "sha-1WithRSAEncryption" 


a signature based on SHA] encrypted with RSA - naming is based on ASN.1 TAG names (see RFC3279) 


5.1.2.20 #define CERTMGR_INIT_CONTEXT (context, size) memset((voidx)context, 0, size); 


macro to initialize a context record to 0 


5.1.2.21 define CERTMGR_START_ERRCODE ( (INT32)(MAX_RESERVED_ERR_CODE - (0 
«MAX ERRCODES PER COMPONENT))) 


first error code available to the certificate manager foundation module 


5.1.2.22 #define CERTPROCESS START ERRCODE ( (INT32)(MAX_- 
RESERVED ERR CODE - (1 x MAX ERRCODES PER COMPONENT)) 


) 


first error code available to the processing framework module 


5.1.2.23 define CERTREVOC STATUS START ERRCODE ( (INT32)(MAX_- 
RESERVED ERR CODE - (5 x MAX ERRCODES PER COMPONENT)) 


) 


first error code available to the revocation status framework module 


5.1.2.24 define CERTSIGNATURE START ERRCODE ( (INT32)(MAX_- 
RESERVED ERR CODE - (3 « MAX ERRCODES PER COMPONENT)) 


) 


first error code available to the signature framework module 


5.1.2.25 define CERTSTORE_START_ERRCODE ( (INT32)(MAX_RESERVED_ERR_CODE - 
(6 x MAX ERRCODES PER COMPONENT))) 


first error code available to the certificate store framework module 
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5.1.2.26 #define ERR BROKEN EXTERN CHAIN ( INT32(CERTMGR START ERRCODE 
-1) 


function return error code indicating the specified certificates could not be arranged into a certificate chain 


5.1.2.27 #define ERR BUFFER TOO SMALL ( (INT32KCERTMGR START ERRCODE - 11) 
) 


function return error code indicating the specified buffer is too small 


5.1.2.28 define ERR DUPLICATE CERTIFICATE ( INT32XCERTMGR START ERRCODE 
-15)) 


function return error code indicating a duplicate certificate exists already 


5.1.2.29 #define ERR FILE IO ERROR ( INT32(CERTMGR START ERRCODE - 5) ) 


function return error code indicating a file input/output error occurred 


5.1.2.30 #define ERR INVALID CERT ID ( (INT32CERTMGR START ERRCODE - 10) ) 


function return error code indicating the specified certificate does not exist 


5.1.2.31 #define ERR INVALID CERTIFICATE ( INT32CERTMGR START ERRCODE - 4) 
) 


function return error code indicating an invalid certificate 


5.1.2.32 #define ERR INVALID SIGNATURE ( INT32(CERTMGR START ERRCODE - 3) ) 


function return error code indicating an invalid signature 


5.1.2.33 #define ERR NO MORE CERTIFICATES ( INT32CERTMGR START ERRCODE 
-13)) 


function return error code indicating there are no more certificates to be retrieved 


5.1.2.34 #define ERR NO ROOT CERTIFICATE ( INT32CERTMGR START ERRCODE - 
2)) 


function return error code indicating a root certificate did not exist 


5.1.2.35 #define ERR STORE IS EMPTY ((INT32(CERTMGR_START_ERRCODE - 12) ) 


function return error code indicating the store is empty 
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5.1.2.36 #define ERR STORE IS FULL ( INT32(CERTMGR START ERRCODE - 9) ) 


function return error code indicating no storage space is available 


5.1.2.37 #define ERR STORE IS UNAVAILABLE ( INT32XCERTMGR START ERRCODE - 
14)) 


function return error code indicating the specified store is not available 


5.1.2.38 define ERR UNKNOWN RESULT CODE ( INT32(CERTMGR START ERRCODE 
-0)) 


function return error code indicating the result code was unknown 


5.1.2.39 #define ERR UNSUPPORTED HASH TYPE ( INT32CERTMGR START - 
ERRCODE - 6) ) 


function return error code indicating the specified hash type is not supported 


5.1.2.40 #define ERR UNSUPPORTED KEY TYPE ( (INT32)(CERTMGR_START_ERRCODE 
-7)) 


function return error code indicating the specified key type is not supported 


5.1.2.41 #define ERR_UNSUPPORTED_OPERATION ( INT32(CERTMGR START - 
ERRCODE - 8) ) 


function return error code indicating the specified operation is not supported 


5.1.2.42 #define MAX ERRCODES PER COMPONENT ((INT32)255) 


number of error codes reserved for each component 


5.1.2.43 #define MAX RESERVED ERR CODE ((INT32)-255) 


first error code available the certificate manager sub system 


5.1.2.44  #define TRUE ((int)1) 


if neither TRUE nor FALSE have been defined, we define both 


5.1.3 Typedef Documentation 
5.1.3.1 typedef int BOOL 


generic boolean type to be used as true false indicator. 
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5.1.3.2 typedef charx CertMgrCertField 


definition for a certificate field identifier 


5.1.3.3 typedef struct _CertMgrCertLinkedList CertMgrCertLinkedList 


Linked list of certificates. This is the structure, which represents a member of the linked list of certificates. 


5.1.3.4 typedef char+ CertMgrCertStatus 


definition for the certificate status 


5.1.3.5 typedef charx CertMgrCipherAlgo 


definition for cipher algorithms 


5.1.3.6 typedef charx* CertMgrExtensionsFldData 


definition for extensions field data 


5.1.3.7 typedef charx CertMgrIssuerFldData 


definition for issuer field data 


5.1.3.8 typedef charx CertMgrIssuerUIDFldData 


definition for issuer UID field data 


5.1.3.9 typedef char+ CertMgrPublicKeyFldData 


definition for public key field data 


5.1.3.10 typedef INT32 CertMgrResult 


function return type. 


5.1.3.11 typedef char+ CertMgrSerialNoFldData 


definition for serial number field data 


5.1.3.12 typedef charx CertMgrSigAlgoFldData 


definition for signature algorithm field data 
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5.1.3.13 typedef char+ CertMgrSigType 


definition for the signature hash/key combination 


5.1.3.14 typedef charx CertMgrStorageld 


definition for the supported certificate store types 


5.1.3.15 typedef charx CertMgrSubjectFldData 


definition for subject field data 


5.1.3.16 typedef charx CertMgrSubject UIDFldData 


definition for subject UID field data 


5.1.3.17 typedef charx CertMgrVersionFldData 


definition for version field data 


5.1.3.18 typedef int INT16 


definition for signed 16 bit integer 


5.1.3.19 typedef long int INT32 


definition for signed 32 bit integer 


5.1.3.20 typedef char INT8 


definition for signed 8 bit integer 


5.1.3.21 typedef unsigned int UINT16 


definition for unsigned 16 bit integer 


5.1.3.22 typedef unsigned long int UINT32 


definition for unsigned 32 bit integer 


5.1.3.23 typedef unsigned char UINT8 


definition for unsigned 8 bit integer 
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5.1.4 Function Documentation 


5.1.4.1 CertMgrResult CertMgrAddCertificateToStore (CertMgrMemBuff x certificate, 
CertMgrCertld x certificateld, CertMgrStorageld storeld) 


This function is used to store the certificate memory buffer in the specified store. 


Sync (or) Async: 


This is a Synchronous API. 


Important Notes: 


e Note: n/a 


Parameters: 


certificate input - specifies the certificate (memory buffer) to be stored. 
certificateld output - the certificate identifier. 


storeld input - the store where the certificate is to be stored. 


Returns: 
Return Type (CertMgrResult) 
e OPERATION_SUCCESS - certificate successfully added 
e ERR_STORE_IS_UNAVAILABLE - the specified store is not available 
e ERR_STORE_IS_FULL - the specified store is full 
e ERR_DUPLICATE_CERTIFICATE - the submitted certificate is already in store 


Prospective Clients: 


External Apps. 


5.1.4.2 CertMgrResult CertMgrAddMetaDataToCert (CertMgrCertld x certificateld, 
CertMgrMetaDatald x metaDatald, CertMgrMemBuff x metaData) 


saves the specified meta data block in the meta data buffer and links the data to a certificate with the 
specified id. 


Sync (or) Async: 


This is a Synchronous API. 


Important Notes: 


e Note: meta data is application centric. The meta data id is generated by the application and is 
guaranteed to be unique over all applications using the meta data facility 


e Note: certificate ids are generated by the certificate store and uniquely identify a certificate stored 
by the certificate manager. 


Parameters: 


certificateld input - a certificate identifier unique over all certificate stores. 
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metaDatald input - a unique identifier for a meta data type. 


metaData input - a data descriptor, specifying a block of data in memory, which represents the meta 
data to be stored. 


Returns: 
Return Type (CertMgrResult) 


e OPERATION SUCCESS - the meta data has been added successfully. 
e ERR STORE IS FULL - no storage space was available to store the meta data 


Prospective Clients: 


External Apps. 


5.1.4.3 CertMgrResult CertMgrDisableCertificate (CertMgrCertld x certificateld) 
This function will change the state of the specified certificate to disabled. 


Sync (or) Async: 


This is a Synchronous API. 


Important Notes: 
e Note: n/a 
Warning: 


n/a 


Parameters: 


certificateld input - a certificate identifier unique over all certificate stores. 


Returns: 
Return Type (CertMgrResult) 


e OPERATION_SUCCESS - indicating that the certificate is disabled. 
e ERR ERR INVALID CERT ID - unknown or invalid certificate ID. 


Prospective Clients: 


External Apps. 


5.1.4.4 CertMgrResult CertMgrEnableCertificate (CertMgrCertld x certificateld) 


This function will change the state of the specified certificate to enabled. 


Sync (or) Async: 


This is a Synchronous API. 
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Important Notes: 
e Note: n/a 
Warning: 
n/a 


Parameters: 


certificateld input - a certificate identifier unique over all certificate stores. 


Returns: 
Return Type (CertMgrResult) 
e OPERATION_SUCCESS - indicating that the certificate is enabled. 


e ERR ERR INVALID CERT ID - unknown or invalid certificate ID. 
Prospective Clients: 


External Apps. 


5.1.4.5 CertMgrResult CertMgrErrorCodeToMessage (CertMgrResult code, char «*« 
resultMessage) 


maps the specified error code to an error message string. 


Sync (or) Async: 


This is a Synchronous API. 


Important Notes: 
e Note: if no message is associated with a particular result code, the function will return an empty 


string 


Parameters: 
code input - a result code, for which the user needs the associated message string. 


resultMessage output - a null terminated message string associated with the specified error code. 


Returns: 
Return Type (CertMgrResult) 


e OPERATION_SUCCESS - message was found. 
e ERR UNKNOWN RESULT CODE - the specified code is unknown. 


Prospective Clients: 


External Apps. 


Example of how this function would be called: 


CertMgrResult result; 
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char *resultMessage; 


result = CertMgrErrorCodeToMessage (ERR UNSUPPORTED OPERATION, &resultMessage) ; 
if (result == RESULT CODE SUCCESS) 
--- resultMessage now contains "unsupported operation" 


5.1.4.6 CertMgrResult CertMgrExtractCertificateData (CertMgrMemBuff x certificate, 
CertMgrCertDescriptor x certificate Descriptor) 


Assemble a certificate record from raw certificate data. 


Sync (or) Async: 


This is a Synchronous API. 


Important Notes: 


e Note: this function must always be used together with CertMgrReleaseCertificateData 


e Note: the certificate field records are allocated in this function, 
to release the allocated memory use CertMgrReleaseCertificateData. 
Warning: 
n/a 


Parameters: 


certificate input - a certificate of any type in raw data. 


certificate Descriptor ouput - the extracted certificate fields from the raw certificate. 


Returns: 


Return Type (CertMgrResult) 


e OPERATION_SUCCESS - indicating that the specified raw certificate is decoded successfully. 


e ERR_INVALID_CERTIFICATE - unknown or incorrectly formatted certificate. 


Prospective Clients: 


External Apps. 


5.1.4.7 CertMgrResult CertMgrGenerateFilBuffSignature (CertMgrSigType algorithm, void x 


keyId, CertMgrFilBuff x msgInFile, CertMgrMemBuff x signature) 
this function will generate a signature over a specified file record. 
Sync (or) Async: 
This is a Synchronous API. 


Important Notes: 


e Note: n/a 
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Parameters: 


algorithm input - a hash algorithm specifier for the signature hash generation. 


keyId input - a key identifier for secure key data access. NOTE: The format of keyld is dependent on 
the specific platform-dependent implementation of secure key handling used by the Cryptography 
plug-in. 

msgInFile input - a message specification record specifiying the message stored in a file. 


signature output - a buffer receiving the generated signature. 


Returns: 
Return Type (CertMgrResult) 


e OPERATION_SUCCESS - indicating that the specified signature has been successfully gener- 
ated. 


e ERR_UNSUPPORTED_OPERATION - the signature generation has not been implemented. 
e ERR UNSUPPORTED HASH TYPE - the specified hash algorithm is not supported. 

e ERR UNSUPPORTED KEY TYPE - the specified key type is not supported. 

e ERR FILE IO ERROR - problem with file access. 


Prospective Clients: 


External Apps. 


Example of how this function would be called: 
CertMgrResult result; 
certMgrMemBuff signature; 
. do some initialization (signature buffer allocation) 
result = CertMgrGenerateMemBuffSignature (CERTMGR_HASH_MD5, key, messagelnFile, £signature); 


if (result == OPERATION SUCCESS) 


5.1.4.8 CertMgrResult CertMgrGenerateMemBuffSignature (CertMgrSigType algorithm, void x 
keyId, CertMgrMemBuff x message, CertMgrMemBuff x signature) 


this function will generate a signature over a specified memory buffer. 


Sync (or) Async: 


This is a Synchronous API. 


Important Notes: 


e Note: n/a 


Parameters: 


algorithm input - a hash algorithm specifier for the signature hash generation. 

keyId input - a key identifier for secure key data access. NOTE: The format of keyld is dependent on 
the specific platform-dependent implementation of secure key handling used by the Cryptography 
plug-in. 
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message input - a message specification record representing the message for which the signature is to 
be generated. 


signature output - a buffer receiving the generated signature. 


Returns: 
Return Type (CertMgrResult) 


e OPERATION_SUCCESS - indicating that the specified signature has been successfully gener- 
ated. 


e ERR_UNSUPPORTED_OPERATION - the signature generation has not been implemented. 
e ERR UNSUPPORTED HASH TYPE - the specified hash algorithm is not supported. 
e ERR UNSUPPORTED KEY TYPE - the specified key type is not supported. 


Prospective Clients: 


External Apps. 


Example of how this function would be called: 
CertMgrResult result; 
certMgrMemBuff signature; 
. do some initialization (signature buffer allocation) 
result = CertMgrGenerateMemBuffSignature (CERTMGR HASH MD5, key, message, «signature); 


if (result == OPERATION SUCCESS) 


5.1.4.9 CertMgrResult CertMgrGetCertificateType (CertMgrMemBuff x certificate, char x 
certificateType) 


Determines the type of the certificate. 


Sync (or) Async: 


This is a Synchronous API. 


Important Notes: n/a 


Warning: 
n/a 


Parameters: 


certificate input - a raw certificate. 


certificateType output - the certificate type. 


Returns: 


Return Type (CertMgrResult) 
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e OPERATION_SUCCESS - the type was successfully determined. 
e ERR_UNKNOWN_CERTIFICATE - the certificate type is unknown. 
e ERR CERTIFICATE FORMAT ERROR - the certificate was incorrectly formatted. 


Prospective Clients: 


External Apps. 


5.1.4.10 CertMgrResult CertMgrPurgeMetaDataFromCert (CertMgrCertld x certificateld) 
removes all meta associated with the specified certificate. 


Sync (or) Async: 


This is a Synchronous API. 


Important Notes: 


e Note: meta data is application centric. The meta data id is generated by the application and is 
guaranteed to be unique over all applications using the meta data facility 


e Note: certificate ids are generated by the certificate store and uniquely identify a certificate stored 
by the certificate manager. 


Parameters: 


certificateld input - a certificate identifier unique over all certificate stores. 


Returns: 
Return Type (CertMgrResult) 


e OPERATION_SUCCESS - the meta data has been successfully removed. 
e ERR INVALID CERT ID - the specfied certificate did not exist in the meta data store. 


Prospective Clients: 


External Apps. 


5.1.4.11 CertMgrResult CertMgrReleaseCertificateData (CertMgrCertDescriptor x 
certificateDescriptor) 


Releases certificate field records allocated in a previous call to CertMgrExtractCertificateData. 
Sync (or) Async: 
This is a Synchronous API. 
Important Notes: 
e Note: n/a 
Warning: 


n/a 
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Parameters: 


certificateDescriptor input - a certificate descriptor. 


Returns: 
Return Type (CertMgrResult) 


e OPERATION_SUCCESS - indicating that the memory allocated for the certificate field records 
has been successfully released. 


Prospective Clients: 


External Apps. 


5.1.4.12 CertMgrResult CertMgrRemoveCertificateFromStore (CertMgrCertld x certificateld) 
This function is used to remove the specified certificate from the specified store. 


Sync (or) Async: 


This is a Synchronous API. 


Important Notes: 
e Note: n/a 


Parameters: 


certificateld input - specifies the certificate to be removed. 


Returns: 
Return Type (CertMgrResult) 
e OPERATION_SUCCESS - certificate was successfully removed 


e Otherwise return the appropriate error 
Prospective Clients: 


External Apps. 


5.1.4.13 CertMgrResult CertMgrRemoveMetaDataFromCert (CertMgrCertld x certificateld, 
CertMgrMetaDatald « metaDatald) 


removes specified meta data from the meta data buffer and unlinks the specified certificate from the re- 
moved meta data. 


Sync (or) Async: 
This is a Synchronous API. 


Important Notes: 


e Note: meta data is application centric. The meta data id is generated by the application and is 
guaranteed to be unique over all applications using the meta data facility 
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e Note: certificate ids are generated by the certificate store and uniquely identify a certificate stored 
by the certificate manager. 
Parameters: 


certificateld input - a certificate identifier unique over all certificate stores. 


metaDatald input - a unique identifier a meta data block in the meta data store. 


Returns: 
Return Type (CertMgrResult) 


e OPERATION_SUCCESS - the meta data has been successfully removed. 
e ERR_INVALID_CERT_ID - the specfied certificate did not exist in the meta data store. 


Prospective Clients: 


External Apps. 


5.1.4.14 CertMgrResult CertMgrRetrieveCertFromStore (CertMgrCtx x context, 
CertMgrMemBuff x certificate, CertMgrCertld x certificateld) 
This function is used to retrieve one or more certificates from the certificate store. 


In the first call the context must be properly initialized. 


Sync (or) Async: 


This is a Synchronous API. 


Important Notes: 


e Note: The context is used to keep track of the retrieval operation over successive calls 

e The context must be initialized to zero during the first call of this function. 

e Use the CERTMGR INIT CONTEXT macro to initialize the context. 

e Additionally, if the retrieval is to be by field, the field descriptor and the retrieveByField flag 


must be set appropriately. 
Parameters: 


context input - The retrieval context. 
certificate output - specifies the certificate memory buffer retrieved. 


certificateId output - specifies the certificate ID retrieved. 
Returns: 


Return Type (CertMgrResult) 


e OPERATION_SUCCESS - certificate status successfully retrieved 
e ERR NO MORE CERTIFICATES - all certificates have been retrieved 


e Otherwise return one appropriate error 


Prospective Clients: 


External Apps. 
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5.1.4.15 CertMgrResult CertMgrRetrieveCertStatus (CertMgrCertld x certificateld, 
CertMgrCertStatus + status) 


This function is used to retrieve the certificate status (whether it is enabled or disabled). 


Sync (or) Async: 


This is a Synchronous API. 


Important Notes: 


e Note: n/a 


Parameters: 


certificateld input - a certificate identifier unique over all certificate stores 


status output - status of current certificate (enabled or disabled). 


Returns: 
Return Type (CertMgrResult) 
e OPERATION_SUCCESS - certificate status successfully retrieved 


e Otherwise return the appropriate error 


Prospective Clients: 


External Apps. 


5.1.4.16 CertMgrResult CertMgrRetrieveMetaDataForCert (CertMgrCertld x certificateld, 
CertMgrMetaDatald x metaDatald, CertMgrMemBuff x metaData) 


retrieves the specified meta data type from the meta data buffer. 


Sync (or) Async: 


This is a Synchronous API. 


Important Notes: 


e Note: meta data is application centric. The meta data id is generated by the application and is 
guaranteed to be unique over all applications using the meta data facility 


e Note: certificate ids are generated by the certificate store and uniquely identify a certificate stored 
by the certificate manager. 


Parameters: 


certificateld input - a certificate identifier unique over all certificate stores. 
metaDatald input - a unique identifier a meta data block in the meta data store. 


metaData output - a buffer descriptor for the buffer receiving the retrieved meta data. 


Returns: 


Return Type (CertMgrResult) 
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e OPERATION SUCCESS - the meta data has been retrieved successfully. 
e ERR INVALID CERT ID - the specified certificate has no entry in the meta data store 
e ERR BUFFER TOO SMALL - the meta data did not fit into the supplied buffer 


Prospective Clients: 


External Apps. 


5.1.4.17 CertMgrResult CertMgrVerifyCertificate (CertMgrCertLinkedList x certificateList) 


Verifies a certificate chain, consisting of one or more certificates. 


Sync (or) Async: 


This is a Synchronous API. 


Important Notes: 
e Note: the certificate chain consists of certificates supplied by the caller and are not part of the 
certificate manager's store 


e to validate the chain, the function must be able to trace the chain from the last in the external 
chain to an existing trusted root 


certificate in the certificate manager's store 


e the linked list of certificates does not need to represent the actual verification scheme (certificate- 
>issuer->certificat...). 


It is sufficient that the set of certificates in the linked list can be rearranged into a proper verifica- 
tion chain 
Warning: 


n/a 


Parameters: 


certificateList input - linked list of certificates, holding all certificates necessary to form a contiguous 
part of a verification chain (see notes above). 


Returns: 
Return Type (CertMgrResult) 


e OPERATION_SUCCESS - an unbroken verification chain of certificates to a trusted root certifi- 
cate exists. 


e ERR BROKEN EXTERN CHAIN - the members of the linked list could not be re-arranged so 
that all were contained in the verification chain. 


e ERR NO ROOT CERTIFICATE - it was impossible to verify the certificate chain to a trusted 
root certificate. 


Prospective Clients: 


External Apps. 
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5.1.4.18 CertMgrResult CertMgr VerifyF BufSigWithCert (char « certificate Type, 
CertMgrMemBuff x certificate, CertMgrFilBuff x msgInFile, CertMgrMemBuff x 
signature) 


Uses a security certificate to verify that a specified signature matches the specified message stored in a file 
record. The certificate determines the signature algorithm and the public key to decode the signature. 


Sync (or) Async: 


This is a Synchronous API. 


Important Notes: 
e Note: n/a 
Warning: 
n/a 


Parameters: 


certificate Type input - certificate type. 
certificate input - a security certificate of any type, used to verify the message signature. 
msgInFile input - the file record descriptor representing the message belonging to the signature. 


signature input - the signature specification which applies to the message. 


Returns: 
Return Type (CertMgrResult) 


e OPERATION_SUCCESS - indicating that the specified signature is a match for the specified 
message. 


e ERR_INVALID_SIGNATURE - specified signature does not match the specified message. 
e ERR_INVALID_CERTIFICATE - unknown or incorrectly formatted certificate. 
e ERR FILE IO ERROR - a file access error occurred. 


Prospective Clients: 


External Apps. 


5.1.4.19 CertMgrResult CertMgrVerifyFileBufferSignature (CertMgrSigType algorithm, 
CertMgrKeyDescr x keyDescriptor, CertMgrFilBuff x msgInFile, CertMgrMemBuff x 
signature) 


Uses a hash type specification and a key descriptor to verify that a specified signature matches the specified 
message stored in a file record. 


Sync (or) Async: 
This is a Synchronous API. 


Important Notes: 


e Note: n/a 
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Warning: 
n/a 


Parameters: 
algorithm input - a hash algorithm specifier applicable to the signature. 
keyDescriptor input - a key descriptor record. 
msgInFile input - a message stored in a file, representing the message belonging to the signature. 


signature input - the signature specification which applies to the message. 


Returns: 
Return Type (CertMgrResult) 


e OPERATION_SUCCESS - indicating that the specified signature is a match for the specified 
message. 


e ERR_INVALID_SIGNATURE - specified signature does not match the specified message. 
e ERR UNSUPPORTED HASH TYPE - the specified hash algorithm is not supported. 
e ERR UNSUPPORTED KEY TYPE - the specified key type is not supported. 


Prospective Clients: 


External Apps. 


5.1.4.20 CertMgrResult CertMgrVerifyMBufSigWithCert (char « certificateType, 
CertMgrMemBuff x certificate, CertMgrMemBuff x message, CertMgrMemBuff x 
signature) 


Uses a security certificate to verify that the specified signature matches a specified message stored in 
memory The certificate determines the signature algorithm and the public key to decode the signature. 


Sync (or) Async: 


This is a Synchronous API. 


Important Notes: 


e Note: n/a 
Warning: 
n/a 


Parameters: 


certificate Type input - the certificate type. 
certificate input - a security certificate of any type, used to verify the message signature. 
message input - the message to which the signature to be verified applies. 


signature input - the signature specification which applies to the message. 


Returns: 


Return Type (CertMgrResult) 
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e OPERATION_SUCCESS - indicating that the specified signature is a match for the specified 
message. 


e ERR_INVALID_SIGNATURE - specified signature does not match the specified message. 
e ERR_INVALID_CERTIFICATE - unknown or incorrectly formatted certificate. 


Prospective Clients: 


External Apps. 


5.1.4.21 CertMgrResult CertMgrVerifyMemBufferSignature (CertMgrSigType algorithm, 
CertMgrKeyDescr x keyDescriptor, CertMgrMemBuff x message, CertMgrMemBuff x 
signature) 


Uses a hash type specification and a key descriptor to verify that a specified signature matches the specified 
message stored in a memory buffer. 


Sync (or) Async: 


This is a Synchronous API. 


Important Notes: 


e Note: n/a 
Warning: 
n/a 


Parameters: 
algorithm input - a hash algorithm specifier applicable to the signature. 
keyDescriptor input - a key descriptor record. 
message input - a message stored in memory, representing the message belonging to the signature. 


signature input - the signature specification which applies to the message. 


Returns: 
Return Type (CertMgrResult) 


e OPERATION_SUCCESS - indicating that the specified signature is a match for the specified 
message. 


e ERR_INVALID_SIGNATURE - specified signature does not match the specified message. 
e ERR UNSUPPORTED HASH TYPE - the specified hash algorithm is not supported. 
e ERR UNSUPPORTED KEY TYPE - the specified key type is not supported. 


Prospective Clients: 


External Apps. 
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5.2 


CertMgrCertProcessing.h File Reference 


5.2.1 Detailed Description 


This file specifies the certificate-processing plug in component for certificate manager. This plug in is 
responsible for verifying and parsing of certificates. 


#include "CertMgr.h" 


Defines 


#define ERR CMPROC INVALID CERTIFICATE (  (INT32«CERTPROCESS_START - 
ERRCODE - 0) ) 


function return error code indicating an incorrectly formatted certificate was specified 


define ERR_CMPROC_UNKNOWN_CERTIFICATE ( (INT32)(CERTPROCESS_START_- 
ERRCODE - 1)) 


function return error code indicating an unknown/unsupported certificate was specified 


Functions 


CertMgrResult CertMgrCertlsMyCertificate (CertMgrMemBuff xcertificate, char certificate- 
Type) 


This function determines the type of a certificate. 


CertMgrResult CertMgrCertProcessingDecodeCert (CertMgrMemBuff xcertificate, CertMgrCert- 
Descriptor «certificateDescriptor) 


This function will assemble a certificate record from a raw certificate. 


CertMgrResult CertMgrCertProcessingRelCrtDta (CertMgrCertDescriptor xcertificateDescriptor) 


Releases certificate field records allocated in a previous call to CertMgrCertProcessingDecodeCert. 


CertMgrResult CertMgrCertProcessingMatchField (CertMgrMemBuff «certificate, CertMgrCert- 
FieldDesc «targetField, BOOL match) 


This function will try to match a specified field with a certificate in raw form. 


CertMgrResult CertMgrCertProcessingCertMatch (CertMgrMemBuff xcertificatel, CertMgrMem- 
Buff xcertificate2, BOOL match) 


This function will compare two raw certificates to determine if the are duplicates (do they match each other). 


5.2.2 Define Documentation 


5.2.2.1 define ERR CMPROC INVALID CERTIFICATE ( INT32CERTPROCESS - 


START ERRCODE - 0) ) 


function return error code indicating an incorrectly formatted certificate was specified 
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5.2.2.2. #define ERR CMPROC. UNKNOWN CERTIFICATE ( (INT32XCERTPROCESS - 
START ERRCODE-1)) 


function return error code indicating an unknown/unsupported certificate was specified 


5.2.3 Function Documentation 


5.2.3.1 CertMgrResult CertMgrCertIsMyCertificate (CertMgrMemBuff x certificate, char x 
certificateType) 


This function determines the type of a certificate. 


Sync (or) Async: 


This is a Synchronous API. 


Important Notes: n/a 


Warning: 
n/a 


Parameters: 


certificate Input - a security certificate in raw data. 


certificate Type Output - the certificate type identifier. 


Returns: 
Return Type (CertMgrResult) 


e OPERATION_SUCCESS - indicating that the certificate type could be determined. 
e ERR_CMPROC_UNKNOWN_CERTIFICATE - unknown/unsupported certificate. 
e ERR_CMPROC_INVALID_CERTIFICATE - incorrectly formatted certificate. 


Prospective Clients: 


External Apps. 


5.2.3.2 CertMgrResult CertMgrCertProcessingCertMatch (CertMgrMemBuff x certificatel, 
CertMgrMemBuff x certificate2, BOOL x match) 


This function will compare two raw certificates to determine if the are duplicates (do they match each 
other). 


Sync (or) Async: 


This is a Synchronous API. 


Important Notes: n/a 
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Warning: 
n/a 


Parameters: 


certificatel Input - first certificate (in raw data format). 
certificate2 Input - second certificate (in raw data format). 


match Output - do the certifictes match. 


Returns: 
Return Type (CertMgrResult) 


e OPERATION_SUCCESS - indicating that the certificate comparison could be completed. 
e ERR_CMPROC_UNKNOWN_CERTIFICATE - unknown/unsupported certificate. 
e ERR_CMPROC_INVALID_CERTIFICATE - incorrectly formatted certificate. 


Prospective Clients: 


External Apps. 


5.2.3.3 CertMgrResult CertMgrCertProcessingDecodeCert (CertMgrMemBuff x certificate, 
CertMgrCertDescriptor x certificate Descriptor) 


This function will assemble a certificate record from a raw certificate. 
Sync (or) Async: 
This is a Synchronous API. 


Important Notes: 
e Note: the memory for the certificate field records is allocated by this function, 
to release the allocated memory use CertMgrCertProcessingRelCrtDta. 
Warning: 
n/a 


Parameters: 


certificate Input - a security certificate in raw data. 


certificateDescriptor Output - The decoded certificate structure, which contains certificate informa- 
tion. 
Returns: 
Return Type (CertMgrResult) 


e OPERATION_SUCCESS - indicating that the certificate is decoded. 
e ERR_CMPROC_UNKNOWN_CERTIFICATE - unknown/unsupported certificate. 
e ERR_CMPROC_INVALID_CERTIFICATE - incorrectly formatted certificate. 


Prospective Clients: 


External Apps. 


Generated on Fri Feb 1 01:01:00 2008 by Doxygen 


5.2 CertMgrCertProcessing.h File Reference 55 


5.2.3.4 CertMgrResult CertMgrCertProcessingMatchField (CertMgrMemBuff x certificate, 
CertMgrCertFieldDesc x targetField, BOOL * match) 


This function will try to match a specified field with a certificate in raw form. 


Sync (or) Async: 


This is a Synchronous API. 


Important Notes: n/a 


Warning: 
n/a 


Parameters: 


certificate Input - a security certificate in raw data. 
targetField Input - the field specification for which a match in the certificate is desired. 


match Output - a boolean, if true indicates that the specified field is a match in the certificate. 


Returns: 
Return Type (CertMgrResult) 


e OPERATION_SUCCESS - indicating that the certificate is supported and was properly format- 
ted. 


e ERR_CMPROC_UNKNOWN_CERTIFICATE - unknown/unsupported certificate. 
e ERR_CMPROC_INVALID_CERTIFICATE - incorrectly formatted certificate. 


Prospective Clients: 


External Apps. 


5.2.3.5 CertMgrResult CertMgrCertProcessingRelCrtDta (CertMgrCertDescriptor * 
certificateDescriptor) 


Releases certificate field records allocated in a previous call to CertMgrCertProcessingDecodeCert. 
Sync (or) Async: 
This is a Synchronous API. 
Important Notes: 
e Note: n/a 
Warning: 
n/a 


Parameters: 


certificateDescriptor Input - The decoded certificate structure, for which the fields should be de- 
allocated. 
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Returns: 
Return Type (CertMgrResult) 
e OPERATION_SUCCESS - indicating successful memory release. 


Prospective Clients: 


External Apps. 
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5.3 CertMgrCryptography.h File Reference 


5.3.1 Detailed Description 


This file specifies the crypto graphic services supplied by the cryptographic plug in component for the 
certificate manager. 


#include "CertMgr.h" 


Defines 


e #define ERR_CMCRYPT_NO_MEMORY ( (INT32)(CERTCRYPTO_START_ERRCODE - 0) ) 


function return error code indicating no memory available 


+ #define ERR_CMCRYPT_UNKNOWN_HASH_TYPE ( (INT32X«CERTCRYPTO_START_- 
ERRCODE - 1)) 


function return error code indicating an unknown hash type was specified 


e #define ERR_CMCRYPT_BUFF_TOO_SMALL ( (INT32)(CERTCRYPTO_START_ERRCODE - 
2)) 


function return error code indicating supplied buffer is to small 


e #define ERR CMCRYPT ALGO NOT SUPPORTED ( (NT32XCERTCRYPTO START - 
ERRCODE - 3) ) 


function return error code indicating the encryption algorithm is not supported 


Functions 


e CertMgrResult CertMgrCryptoGetHashBuffSize (CertMgrSigType hashType, UINT32 xsize) 


This function is used to determine the size of a hash for a particular hash algorithm type. 


e CertMgrResult CertMgrCryptolnitHash (CertMgrSigType hashType, void **context) 


This function is used to allocate and initialize a hash processing context record for the specified algorithm. 
This function is part of a triplet of functions (initialize, process and finalise), which are used together to 
generate a message hash for the specified hash type. 


e CertMgrResult CertMgrCryptoProcessHash (void *context, CertMgrMemBuff *message) 


This function is used to generate a message hash over arbitrarily long messages. This function is part of a 
triplet of functions (initialize, process and finalise), which are used together to generate a message hash for 
the specified hash type. 


e CertMgrResult CertMgrCryptoFinaliseHash (void «context, CertMgrMemBuff «message, CertMgr- 
MemBuff «hash) 


This function is invoked at the end of a sequence of message hash processing calls to finalise the hash 
computation. The function generates the message hash and de-allocates the context record. 


e void CertMgrCryptoGenerateHash (CertMgrSigType hashType, CertMgrMemBuff «message, Cert- 
MgrMemBuff xhash) 


This function is used to generate a hash value for the specified hash type over a single message buffer. 
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e void CertMgrCryptoDecrypt (CertMgrCipherAlgo algorithm, CertMgrKeyDescr *key, CertMgr- 
MemBuff *message, CertMgrMemBuff «plainText) 


This function is used to decrypt the specified message with the specified key and decryption algorithm. 


e CertMgrResult CertMgrCryptoEncrypt (void xkeyId, CertMgrCipherAlgo algorithm, CertMgrMem- 
Buff «plainText, CertMgrMemBuff «message) 


This function is used to encrypt the specified plain text with the specified key and encryption algorithm. 


5.3.2 Define Documentation 


5.3.2.1 #define ERR CMCRYPT ALGO NOT SUPPORTED ( (INT32)(CERTCRYPTO_- 
START_ERRCODE - 3) ) 


function return error code indicating the encryption algorithm is not supported 


5.3.2.2 #define ERR CMCRYPT BUFF TOO SMALL ( (INT32)(CERTCRYPTO_START_- 
ERRCODE - 2) ) 


function return error code indicating supplied buffer is to small 


5.3.2.3 #define ERR CMCRYPT NO MEMORY ( (INT32)(CERTCRYPTO_START_- 
ERRCODE - 0) ) 


function return error code indicating no memory available 


5.3.2.4 #define ERR CMCRYPT UNKNOWN HASH TYPE ( INT32XCERTCRYPTO - 
START ERRCODE - 1)) 


function return error code indicating an unknown hash type was specified 


5.3.3 Function Documentation 


5.3.3.1 void CertMgrCryptoDecrypt (CertMgrCipherAlgo algorithm, CertMgrKeyDescr x key, 
CertMgrMemBuff x message, CertMgrMemBuff x plainText) 


This function is used to decrypt the specified message with the specified key and decryption algorithm. 


Sync (or) Async: 


This is a Synchronous API. 


Important Notes: 


e Note: n/a 


Parameters: 


algorithm input - the decryption algorithm to use. 


key input - a public key descriptor. 
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message input - the encrypted message. 


plainText output - the decrypted message. 


Returns: 


Return Type (void) 


Prospective Clients: 


Certificate manager foundation API. 


Example of how this function would be called: 


CertMgrResult result; 
CertMgrMemBuff plainText; 
CertMgrKeyDescr key, 


. initialize (plainText, key etc.) 


CertMgrCryptoDecrypt (CERTMGR CIPHER RSA, &key, message, &plainText ); 


5.3.3.2 CertMgrResult CertMgrCryptoEncrypt (void « keyld, CertMgrCipherAlgo algorithm, 
CertMgrMemBuff x plainText, CertMgrMemBuff x message) 


This function is used to encrypt the specified plain text with the specified key and encryption algorithm. 


Sync (or) Async: 


This is a Synchronous API. 


Important Notes: 


e Note: n/a 


Parameters: 


keyId input - a key identifier for secure key data access. NOTE: The format of keyId is dependent on 
the specific platform-dependent implementation of secure key handling used by the Cryptography 
plug-in. 

algorithm input - the encryption algorithm to be used. 

plainText input - the plain text message. 


message output - the encrypted message. 


Returns: 
Return Type (CertMgrResult) 
e OPERATION_SUCCESS - message was successfully encrypted 
Return Type (void) 


Prospective Clients: 


Certificate manager foundation API. 
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Example of how this function would be called: 


CertMgrResult result; 


CertMgrMemBuff message; 
void xkeyId; 


initialize (message etc.) 


CertMgrCryptoEncrypt (keyId, CERTMGR CIPHER RSA, plainText, message ); 


5.3.3.3 CertMgrResult CertMgrCryptoFinaliseHash (void x context, CertMgrMemBuff x message, 
CertMgrMemBuff x hash) 


This function is invoked at the end of a sequence of message hash processing calls to finalise the hash 
computation. The function generates the message hash and de-allocates the context record. 


Sync (or) Async: 


This is a Synchronous API. 


Important Notes: 
e Note: n/a 


Parameters: 


context input - The address of a context record specified as a pointer to void. 
message input - a message specification record. 


hash output - a buffer, which will receive the computed hash. 


Returns: 
Return Type (CertMgrResult) 


e OPERATION_SUCCESS - the hash was correctly finalised. 
e ERR CMCRYPT BUFF TOO SMALL - the supplied hash buffer is to small. 


Prospective Clients: 


Certificate manager foundation API. 


Example of how this function would be called: 


void xhashContext; 


CertMgrMemBuff *messageBuffer; 

CertMgrSigType hashType = CERTMGR_HASH_MD2_RSA; 
CertMgrMemBuff hash; 

UINT32 hashBuffSize; 


CertMgrCryptoGetHashBuffSize (hashType, &hashBuffSize) ; 
initialize hash buffer etc. 
result = CertMgrCryptoInitHash( hashType, éhashContext ); 


if (result == RESULT CODE SUCCESS) 
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moreInMessage = getMessageBuffer(targetMessage, messageBuffer) 
while (moreInMessage == TRUE) 
{ 
CertMgrCryptoProcessHash(hashContext, messageBuffer) ; 
moreInMessage = getMessageBuffer(targetMessage, messageBuffer) ; 
} 
CertMgrCryptoFinaliseHash(hashContext, &hash) 


5.3.3.4 void CertMgrCryptoGenerateHash (CertMgrSigType hashType, CertMgrMemBuff x 
message, CertMgrMemBuff x hash) 


This function is used to generate a hash value for the specified hash type over a single message buffer. 


Sync (or) Async: 


This is a Synchronous API. 


Important Notes: 
e Note: n/a 


Parameters: 


hashType input - the desired hash type. 
message input - a message specification record. 


hash output - a buffer receiving the computed hash. 


Returns: 
Return Type (CertMgrResult) 


e OPERATION_SUCCESS - the hash was correctly computed. 
e ERR CMCRYPT UNKNOWN HASH TYPE - the specified hash type is not supported. 
e ERR_CMCRYPT_BUFF_TOO_SMALL - the supplied hash buffer was too small. 


Prospective Clients: 


Certificate manager foundation API. 


Example of how this function would be called: 


CertMgrSigType hashType = CERTMGR_HASH_MD2_RSA; 


CertMgrMemBuff hash; 
UINT32 hashBuffSize; 
CertMgrMemBuf f *messageBuffer; 


CertMgrCryptoGetHashBuffSize (hashType, &hashBuffSize) ; 
. initialize hash buffer etc. 
result = CertMgrCryptoGenerateHash( hashType, message, hash ); 


if (result == RESULT_CODE_SUCCESS) 
{ 


} 
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5.3.3.5 CertMgrResult CertMgrCryptoGetHashBuffSize (CertMgrSigType hashType, UINT32 x 
size) 


This function is used to determine the size of a hash for a particular hash algorithm type. 


Sync (or) Async: 


This is a Synchronous API. 


Important Notes: 
e Note: n/a 
Parameters: 


hashType input - The type of hash algorithm for which we want the hash size. 
size output - The size of the hash in bytes. 


Returns: 
Return Type (CertMgrResult) 


e OPERATION_SUCCESS - the component was successfully initialized. 
e ERR CMCRYPT UNKNOWN HASH TYPE - the specified hash type was unknown. 


Prospective Clients: 


Certificate manager foundation API. 


5.3.3.6 CertMgrResult CertMgrCryptolnitHash (CertMgrSigType hashType, void x*x context) 


This function is used to allocate and initialize a hash processing context record for the specified algorithm. 
This function is part of a triplet of functions (initialize, process and finalise), which are used together to 
generate a message hash for the specified hash type. 

Sync (or) Async: 


This is a Synchronous API. 


Important Notes: 


e Note: n/a 


Parameters: 


hashType input - The hash type specification. 


context output - The address of a pointer to void, which will receive the context record address. 


Returns: 
Return Type (CertMgrResult) 


e OPERATION_SUCCESS - the context record was properly allocated and initialized. 
e ERR CMCRYPT NO MEMORY - no memory to allocate a context record. 
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e ERR CMCRYPT UNKNOWN HASH TYPE - the hash type is not supported. 


Prospective Clients: 


Certificate manager foundation API. 


Example of how this function would be called: 


void xhashContext; 


CertMgrMemBuff *messageBuffer; 

CertMgrSigType hashType = CERTMGR_HASH_MD2_RSA; 
CertMgrMemBuff hash; 

UINT32 hashBuffSize; 


CertMgrCryptoGetHashBuffSize (hashType, &hashBuffSize) ; 
initialize hash buffer etc. 
result = CertMgrCryptoInitHash( hashType, &hashContext ); 
if (result == RESULT CODE SUCCESS) 
{ 
moreInMessage = getMessageBuffer(targetMessage, messageBuffer) 
while (moreInMessage == TRUE) 
{ 
CertMgrCryptoProcessHash(hashContext, messageBuffer) ; 
moreInMessage = getMessageBuffer(targetMessage, messageBuffer) ; 


} 
CertMgrCryptoFinaliseHash(hashContext, &hash) 


5.3.3.7 CertMgrResult CertMgrCryptoProcessHash (void x context, CertMgrMemBuff « message) 


This function is used to generate a message hash over arbitrarily long messages. This function is part of a 
triplet of functions (initialize, process and finalise), which are used together to generate a message hash for 
the specified hash type. 

Sync (or) Async: 


This is a Synchronous API. 


Important Notes: 


e Note: if the message fits into a single buffer, we use the other supplied functions for this (Cert- 
MgrCryptoGenerateHash) 


Parameters: 


context input - The address of a context record. 


message input - a message specification record. 


Returns: 


Return Type (CertMgrResult) 
e OPERATION_SUCCESS - the hash was correctly computed over the specified message block 
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Prospective Clients: 


Certificate manager foundation API. 


Example of how this function would be called: 


void *hashContext; 

CertMgrMemBuff *messageBuffer; 

CertMgrSigType hashType = CERTMGR_HASH_MD2_RSA; 
CertMgrMemBuf f hash; 

UINT32 hashBuffSize; 


CertMgrCryptoGetHashBuffSize (hashType, 


initialize hash buffer etc. 


result = CertMgrCryptoInitHash( hashType, 


if (result == RESULT CODE SUCCESS) 
{ 


&hashBuffSize); 


ghashContext ); 


moreInMessage = getMessageBuffer(targetMessage, messageBuffer) 


while (moreInMessage == TRUE) 

{ 
CertMgrCryptoProcessHash (hashContext, messageBuffer) ; 
moreInMessage = getMessageBuffer(targetMessage, messageBuffer) ; 


} 


CertMgrCryptoFinaliseHash (hashContext, 
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5.4. CertMgrDebug.h File Reference 


5.4.1 Detailed Description 


This is the header file for the LiMo Certificate Manager Foundation API. 


Defines 


e define CM LOG 1 
e #define CERTMGR_DEBUG(fmt, args...) 


5.4.2 Define Documentation 
5.4.2.1 #define CERTMGR_DEBUG(fmt, args...) 
Value: 


printf ("Func $s(on line %d of file $s): "fmt"Nn", \ 
_ FUNCTION, LINE_, FILE_, ##args) 
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5.5 


CertMgrInternal.h File Reference 


5.5.1 Detailed Description 


This is the header file for the LiMo Certificate Manager Foundation API. 


#include "CertMgr.h" 


#include "CertMgrSignature.h" 


#include "CertMgrRevocationStatus.h" 


Data Structures 


struct _SignaturelnitParas 
struct _CertList 


Defines 


#define CIPHER_PADDING 1 

#define MAX NAME LENGTH 256 

#define MAX TYPE LENGTH 256 

#define MAX PUBKEY LENGTH (2x1024) 

#define MAX SIG ALGO LENGTH 32 

#define MAX CERT TYPE LENGTH 10 

#define HASH MD2 LENGTH 16 

#define HASH  MD5 LENGTH 16 

#define HASH SHA1 LENGTH 20 

#define HASH MAX LENGTH 20 

#define MAX STORE ID LENGTH 20 

#define MAX STORE TYPE LENGTH 20 

#define MAX TYPE SIZE 50 

#define MAX ID SIZE 50 

#define MAX DATA SIZE 256 

#define MAX UINT32 STRLEN 11 

#define FLAG_ISSUER 0 

#define FLAG SUBJECT 1 

#define CERTMGR X509 TYPE "X509" 

#define METADATA TYPELEN SIZE (sizeof(UINT32)) 

#define METADATA OWNERLEN SIZE (sizeof(UINT32)) 

#define METADATA LENGTH SIZE (sizeof(UINT32)) 

#define MAX BUFFER SIZE (4x1024) 

#define METADATA PATH "./" 

#define ERR INPUT PARAMETER ( INT32CERTMGR START ERRCODE - 16) ) 
#define ERR UNKNOWN. CERTIFICATE ( INT32CERTMGR START ERRCODE - 17) ) 
#define ERR CERTIFICATE FORMAT ERROR ( (INT32XCERTMGR START ERRCODE - 
18) ) 

#define ERR CMPROC UNSUPPORTED SIG ALGO ( (INT32(CERTMGR_START_- 
ERRCODE - 19) ) 


#define ERR NOT IMPLEMENTED ( (INT32XCERTMGR START ERRCODE - 20) ) 
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#define ERR EXTERN CHAIN IS EMPTY ( (INT32)(CERTMGR_START_ERRCODE - 21) ) 


#define ERR DIGEST INIT ( (INT32)(CERTMGR_START_ERRCODE - 22) ) 

#define ERR DIGEST UPDATE ( (INT32XCERTMGR START ERRCODE - 23) ) 

#define ERR DIGEST FINAL ( INT32XCERTMGR START ERRCODE - 24) ) 

#define ERR NO TARGET FIELD ( INT32XCERTMGR START ERRCODE - 25) ) 

#define ERR PLUGIN SYM ( (INT32XCERTMGR START ERRCODE - 26) ) 

#define ERR INVALID ROOT CERTIFICATE ( (INT32XCERTMGR START ERRCODE - 
27) ) 

#define ERR_PLUGIN_IS_UNAVAILABLE ( (INT32)(CERTMGR_START_ERRCODE - 28) ) 
#define ERR FILE NOT EXIST ( (INT32XCERTMGR START ERRCODE - 29) ) 

#define ERR INDEX NOT FOUND ( (INT32XCERTMGR START ERRCODE - 30) ) 

#define ERR DUPLICATE NODE ( (INT32XCERTMGR START ERRCODE - 31) ) 

#define ERR INVALID ID ( (INT32XCERTMGR START ERRCODE - 32) ) 

#define OPERATION SUCCESS ( (UINT32)0 ) 

define ERR CMSTORE IS FULL ( (INT32XCERTSTORE START ERRCODE - 1) ) 

#define ERR FILE OPEN ( (UINT32)XCERTSTORE START ERRCODE - 6) ) 

#define ERR CERT NOFIND ( (UINT32XCERTSTORE START ERRCODE - 7) ) 

#define ERR MEM MALLOC ( (UINT32XCERTSTORE START ERRCODE - 8) ) 

#define ERR MAX CERTID ( (UINT32XCERTSTORE START ERRCODE - 11) ) 

#define ERR SYSTEM CALL ( (UINT32XCERTSTORE START ERRCODE - 12) ) 

#define ERR FILE CREATE ( (UINT32)XCERTSTORE START ERRCODE - 13) ) 

#define ERR UNSUPPORTED CERT TYPE ( (UINT32XCERTSTORE START ERRCODE - 
14)) 

#define ERR INVALID METADATA ID ( (INT32XCERTMETADATA START ERRCODE - 
10) ) 

#define ERR UNSUPPORTED METADATA (  (INT32(CERTMETADATA_START - 
ERRCODE - 11) ) 

#define ERR_CMSIG_DECRYPT_FAILED ( (INT32)(CERTSIGNATURE_START_ERRCODE 
-2)) 


Typedefs 


typedef _SignatureInitParas SignatureInitParas 

typedef _CertList CertList 

typedef CertMegrResult(*) CertMgrCryptoInitHash_t (CertMgrSigType hashType, void 
**context) 

typedef CertMgrResultGs) CertMgrCryptoProcessHash_t (void xcontext, CertMgrMemBuff 
*message) 

typedef CertMgrResult(*) CertMgrCryptoFinaliseHash_t (void *context, CertMgrMemBuff 
«message, CertMgrMemBuif xhash) 

typedef void(*) CertMgrCryptoDecrypt_t (CertMgrCipherAlgo algorithm, CertMgrKeyDescr 
xkey, CertMgrMemBuff «message, CertMgrMemBuff «plainText) 

typedef CertMgrResultGs) CertMgrSignatureInitContext_t (CertMgrSigType algorithm, void 
**context) 

typedef CertMgrResult(x) CertMgrSignatureVerify_t (void *context, CertMgrKeyDescr *key- 
Descriptor, CertMgrMemBuff «message, BOOL final, CertMgrMemBuff xsignature) 

typedef void(*) CertMgrSignatureReleaseContext t (void x*context) 

typedef CertMgrResult(*) CertMgrSignatureLoadCryptolnfo t (CertMgrPlugInDescr *crypto- 
PlugIns, UINT32 noOfPluglns) 
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typedef CertMgrResult(+) CertMgrSignaturelnitialize_t (CertMgrSigType algorithm, char init- 
Paras) 

typedef CertMgrResult(«) CertMgrCertIsMyCertificate_t (CertMgrMemBuff «certificate, char 
xcertificate Type) 

typedef CertMerResult(*) CertMgrCertProcessingDecodeCert t (CertMgrMemBuff «certificate, 
CertMgrCertDescriptor «certificate Descriptor) 

typedef CertMgrResult(x) CertMgrCertProcessingRelCrtDta_t  (CertMerCertDescriptor 
«certificate Descriptor) 

typedef CertMgrResult(x) CertMgrCertProcessingMatchField_t (CertMgrMemBuiff «certificate, 
CertMgrCertFieldDesc *targetField, BOOL +«match) 

typedef CertMgrResult(+) CertMgrCertProcessingCertMatch_t (CertMgrMemBuff «certificate 1, 
CertMgrMemBuff *certificate2, BOOL *match) 

typedef CertMgrResult(«) StoreInitializePtr (CertMgrStorageld storeld, char x*initParas) 

typedef CertMgrResult(x) StoreStoreCertificatePtr (CertMgrMemBuff «certificate, CertMgrCertld 
*certificateld) 
typedef CertMgrkResult(*) StoreRemoveCertificatePtr (CertMgrCertld xcertificateld) 

typedef CertMgrResult(+) StoreEnableCertificatePtr (CertMgrCertld «certificateld) 

typedef CertMgrResult(+) StoreDisableCertificatePtr (CertMgrCertld xcertificateld) 

typedef CertMerResult(*) StoreRemoveAllUserCertificatesPtr (void) 

typedef CertMgrResult(+) StoreRetrieveCertificatePtr (CertMgrCtx *context, CertMgrMemBuff 
xcertificate, CertMgrCertld *certificateld) 

typedef CertMgrResult(x) StoreRetrieveCertificateStatusPtr (CertMgrCertld xcertificateld, Cert- 
MgrCertStatus xstatus) 

typedef CertMgrResult(x) CertMgrRevocationStatusVerify t (CertMgrCertDescriptor x, enum 
CertMgrRevocationStatus x) 
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5.6 CertMgrPlugin.h File Reference 


5.6.1 Detailed Description 


This is the header file for LiMo Certificate Manager Plug-in framework API. 


#include "CertMgrInternal.h" 


Data Structures 


e struct CertMgrPlugin 
e struct CertMgrPluginType 


Typedefs 


e typedef _CertMgrPlugin CertMgrPlugin 
e typedef _CertMgrPluginType CertMgrPluginType 


Enumerations 


e enum CertMgrPlugInType { 


CERTMGR STORE, CERTMGR_DIGITALSIGNATURE, CERTMGR_CRYPTOGRAPHY, 
CERTMGR STATUS, 


CERTMGR PROCESSING ) 


Functions 


e CertMgrPlugin * CertMgrFindPlugin (CertMgrPlugInType type, char xid) 
e CertMgrPlugin * CertMgrFindNextPlugin (CertMgrPlugin *current) 

e void CertMgrlnit (void) 

e void CertMgrExit (void) 


5.6.2 Enumeration Type Documentation 
5.6.2.1 enum CertMgrPlugInType 
Different plug-in types 


Enumerator: 
CERTMGR_STORE Certificate Store Plug-in 
CERTMGR_DIGITALSIGNATURE Digital signature plug-in 
CERTMGR_CRYPTOGRAPHY Certificate cryptography plug-in 
CERTMGR_STATUS Certificate revocation plug-in 
CERTMGR_PROCESSING Certificate processing plug-in 
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5.6.3 Function Documentation 
5.6.3.1 void CertMgrExit (void) 


Release all resources used for plug-ins. 


5.6.3.2 CertMgrPlugin+ CertMgrFindNextPlugin (CertMgrPlugin « current) 


Retrives the next plugin in the same plugin type. 


5.6.3.3 CertMgrPlugin*x CertMgrFindPlugin (CertMgrPlugInType type, char x id) 
Retrives the plugin by type and ID. 


Parameters: 
type -plugin type, for example, "Store", "DigitalSignature". 


id -plugin id. for example "md5", "RSA". For store plugin, if the id is null, then returns the default 
plugin. 


5.6.3.4 void CertMgrInit (void) 


Initilize all the plug-ins. 
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5.7 CertMgrRevocationStatus.h File Reference 


5.7.1 Detailed Description 


This file specifies the revocation status plug in componenet for certificate manager. This plug in is respon- 
sible for handling certificate status request. 


#include "CertMgr.h" 


Defines 


e #define ERR CMREVOC NO REVOC STATUS ( (INT32)XCERTREVOC STATUS START - 
ERRCODE - 0) ) 


function return error code indicating no revocation status is available for the specified certificate 


+ #define ERR CMREVOC INVAL CERTIFICATE ( (INT32XCERTREVOC STATUS START - 
ERRCODE - 1) ) 


function return error code indicating the specified certificate is invalid 


Enumerations 


e enum CertMgrRevocationStatus [ CERTMGR_NOT_REVOKED, CERTMGR REVOKED ) 


Functions 


e CertMgrResult CertMgrRevocationStatusVerify (CertMgrCertDescriptor «certificateDescriptor, 
enum CertMgrRevocationStatus xstatus) 


This function will obtain the current revocation status of a certificate. 


5.7.2 Define Documentation 


5.7.2.1 define ERR CMREVOC INVAL CERTIFICATE ( (INT32)(CERTREVOC_STATUS_- 
START_ERRCODE - 1)) 


function return error code indicating the specified certificate is invalid 


5.7.2.2. #define ERR_CMREVOC_NO_REVOC_STATUS ( (INT32)(CERTREVOC_STATUS_- 
START_ERRCODE - 0) ) 


function return error code indicating no revocation status is available for the specified certificate 


5.7.3 Enumeration Type Documentation 
5.7.3.1 enum CertMgrRevocationStatus 


The revocation status 
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Enumerator: 
CERTMGR_NOT_REVOKED the certificate has not been revoked 
CERTMGR_REVOKED the certificate has been revoked 


5.7.4 Function Documentation 


5.7.4.1 CertMgrResult CertMgrRevocationStatusVerify (CertMgrCertDescriptor * 
certificateDescriptor, enum CertMgrRevocationStatus x status) 


This function will obtain the current revocation status of a certificate. 


Sync (or) Async: 


This is a Synchronous API. 


Important Notes: 


e Note: n/a 


Warning: 


n/a 


Parameters: 
certificateDescriptor Input - The decoded certificate structure, which contains certificate information. 


status Output - Status indicating whether the certificate is revoked 


Returns: 
Return Type (CertMgrResult) 


e OPERATION_SUCCESS - Indicating revocation status could be established 


e ERR CMREVOC NO REVOC STATUS - Indicating that the revocation status could not be 
established 


e ERR CMREVOC INVAL CERTIFICATE - Unknown/unsupported certificate. 


Prospective Clients: 


External Apps. 
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5.8 CertMgrSignature.h File Reference 


5.8.1 Detailed Description 


This is the component which implements digital signature capability for the certificate manager. 


#include "CertMgr.h" 


Data Structures 


e struct CertMgrPlugInDescr 


Defines 


e #define ERR CMSIG NO MEMORY ( INT32XCERTSIGNATURE START ERRCODE - 0) ) 


function return error code indicating no memory available 


+ #define ERR_CMSIG_UNSUPPORTED_HASH_TYP ( (INT32XCERTSIGNATURE START - 
ERRCODE - 1) ) 


function return error code indicating the specified hash type is not supported 


Functions 


e CertMgrResult CertMgrSignatureLoadCryptolnfo (CertMgrPlugInDescr *cryptoPlugIns, UINT32 
noOfPluglns) 


This function is used to inform the signature module, where it can find the various crypto plug-ins. 


e CertMgrResult CertMgrSignatureInitContext (CertMgrSigType algorithm, void **context) 


This function is used to allocate and initialize a context record, used for signature verification and genera- 
tion, whenever a message is too big to fit into a single processing buffer. The function is the mirror function 
to CertMgrSignatureReleaseContext, which releases the context. The process of verification or generation 
of a signature over an arbitrarily long message, follows a sequence laid out below: 


— allocate and initialize context 
— verify or generate (repeated n times) 


— release context. 


e void CertMgrSignatureReleaseContext (void *context) 


This function is used to de-allocate a context record, used for signature verification and generation, when- 
ever a message is too big to fit into a single processing buffer and the verificating or generating function 
must be called multiple times. The function is the mirror function to CertMgrSignaturelnitContext, which 
allocates and initializes the context. The process of verification or generation of a signature over an arbi- 
trarily long message, follows a sequence laid out below: 

— allocate and initialize context 

— verify or generate (repeated n times) 


— release context. 


e CertMgrResult CertMgrSignature Verify (void «context, CertMgrKeyDescr xkeyDescriptor, Cert- 
MgrMemBuff «message, BOOL final, CertMgrMemBuff «signature) 
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This function is used to verify that a specified message has the specified signature based on the specified 
key and digest algorithm. Note, the digest algorithm is being specified when the context is allocated with 
the CertMgrSignaturelnitContext function. The process of verification or generation of a signature over an 
arbitrarily long message, follows a sequence laid out below: 


— allocate and initialize context 
— verify or generate (repeated n times) 


— release context. 


e CertMgrResult CertMgrSignatureGenerate (void *context, void xkeyld, CertMgrMemBuff 
«message, BOOL final, CertMgrMemBuiff xsignature) 


This function is used to generate a signature over an arbitrarily long message. The signature is based on 
some key identifier and a digest algorithm. The process of verification or generation of a signature over an 
arbitrarily long message, follows a sequence laid out below: 


— allocate and initialize context 
— verify or generate (repeated n times) 


— release context. 


e CertMgrResult CertMgrSignatureInitialize (CertMgrSigType algorithm, char xinitParas) 


This function is used to initialize the signature component. 


5.8.2 Define Documentation 


5.8.2.1 #define ERR_CMSIG_NO_MEMORY ( (INT32XCERTSIGNATURE START - 
ERRCODE - 0) ) 


function return error code indicating no memory available 


5.8.2.2 #define ERR CMSIG UNSUPPORTED HASH TYP ( (INT32)(CERTSIGNATURE_- 
START ERRCODE-1)) 


function return error code indicating the specified hash type is not supported 


5.8.3 Function Documentation 


5.8.3.1 CertMgrResult CertMgrSignatureGenerate (void x context, void « keyld, 
CertMgrMemBuff x message, BOOL final, CertMgrMemBuff x signature) 


This function is used to generate a signature over an arbitrarily long message. The signature is based on 
some key identifier and a digest algorithm. The process of verification or generation of a signature over an 
arbitrarily long message, follows a sequence laid out below: 


e allocate and initialize context 
e verify or generate (repeated n times) 
e release context. 

Sync (or) Async: 


This is a Synchronous API. 
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Important Notes: 


e Note: The digest algorithm is being specified during context allocation 
e Note: The key identifier must allow secure handling of the signing key. 


e Note: Handling of private signing keys depends on the local security set up. 


Parameters: 


context input/output - a context record address previously allocated with a call to CertMgrSignature- 
InitContext. 


keyId input - a key identifier for secure key data access. 
message input - a message specification record (either the whole message or a fragment). 


final input - a boolean, if true, signals that the current invocation contains the last message part in its 
message buffer. 


signature input - a signature descriptor record. 


Returns: 
Return Type (CertMgrResult) 


e OPERATION_SUCCESS - the signature is correct for the specified message. 
e ERR_CMSIG_UNSUPPORTED_HASH_TYP - the specified algorithm is not supported. 


Prospective Clients: 


Certificate manager foundation API. 


Example of how this function would be called: 


CertMgrResult result; 


void *context; 
int iteration; 


CertMgrFilBuff x«msgOnFile 
CertMgrMemBuff «message; 


some initialization etc. 


result = CertMgrSignatureInitContext (CERTMGR HASH MD2, &context ); 


if (result == OPERATION SUCCESS) 
{ 
while( allDone == FALSE && moreBuffs == TRUE ) 
{ 
moreBuffs = getNextMessageBuffer (msgOnFile, message, ...) 


CertMgrSignatureGenerate(context, keyDescriptor, message, FALSE, signature) 
} 
CertMgrSignatureGenerate(context, keyDescriptor, message, TRUE, signature) 
CertMgrSignatureReleaseContext (context) 


5.8.3.2 CertMgrResult CertMgrSignatureInitContext (CertMgrSigType algorithm, void ** 
context) 


This function is used to allocate and initialize a context record, used for signature verification and genera- 
tion, whenever a message is too big to fit into a single processing buffer. The function is the mirror function 
to CertMgrSignatureReleaseContext, which releases the context. The process of verification or generation 
of a signature over an arbitrarily long message, follows a sequence laid out below: 
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e allocate and initialize context 
e verify or generate (repeated n times) 
e release context. 

Sync (or) Async: 


This is a Synchronous API. 


Important Notes: 


e Note: n/a 


Parameters: 


algorithm input - specifies the digest algorithm for which the signature context is used. 


context output - address of variable, receiving the context address. 


Returns: 
Return Type (CertMgrResult) 


e OPERATION_SUCCESS - the context was successfully allocated and initialized. 
e ERR_CMSIG_NO_MEMORY - the context record could not be allocated. 
e ERR_CMSIG_UNSUPPORTED_HASH_TYP - the specified algorithm is not supported. 


Prospective Clients: 


Certificate manager foundation API. 


Example of how this function would be called: 


CertMgrResult result; 
void *context; 


result = CertMgrSignatureInitContext (CERTMGR_HASH_MD2, &context ); 


if (result == OPERATION_SUCCESS) 


5.8.3.3 CertMgrResult CertMgrSignaturelnitialize (CertMgrSigType algorithm, char x initParas) 
This function is used to initialize the signature component. 
Sync (or) Async: 

This is a Synchronous API. 


Important Notes: 


Note: n/a 


Parameters: 


algorithm input - specifies the signature type. 
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initParas input - contains initialization string which is used to connect to proper cryptography plug-in. 


Returns: 


Return Type (RESULT_CODE_T) 


OPERATION_SUCCESS - the component was successfully initialized. 


Prospective Clients: 


Certificate manager foundation API. 


5.8.3.4 CertMgrResult CertMgrSignatureLoadCryptoInfo (CertMgrPlugInDescr « cryptoPluglns, 
UINT32 noOfPlugIns) 


This function is used to inform the signature module, where it can find the various crypto plug-ins. 


Sync (or) Async: 


This is a Synchronous API. 


Important Notes: 
e Note: n/a 


Parameters: 


cryptoPlugIns input - an array of cryptographic plug-in descriptors needed to access the cryptographic 
functions of the CM. 


noOfPlugIns input - the number of plug-in descriptors in the array. 


Returns: 
Return Type (CertMgrResult) 
e OPERATION_SUCCESS - the plug-in descriptors were successfully loaded. 


Prospective Clients: 


Certificate manager foundation API. 


5.8.3.5 void CertMgrSignatureReleaseContext (void « context) 


This function is used to de-allocate a context record, used for signature verification and generation, when- 
ever a message is too big to fit into a single processing buffer and the verificating or generating function 
must be called multiple times. The function is the mirror function to CertMgrSignatureInitContext, which 
allocates and initializes the context. The process of verification or generation of a signature over an arbi- 
trarily long message, follows a sequence laid out below: 


e allocate and initialize context 
e verify or generate (repeated n times) 


e release context. 
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Sync (or) Async: 


This is a Synchronous API. 


Important Notes: 


e Note: n/a 


Parameters: 


context input - the context to be released. 


Returns: 


Return Type (void) 


Prospective Clients: 


Certificate manager foundation API. 


5.8.3.6 CertMgrResult CertMgrSignatureVerify (void x context, CertMgrKeyDescr x 
keyDescriptor, CertMgrMemBuff x message, BOOL final, CertMgrMemBuff x signature) 


This function is used to verify that a specified message has the specified signature based on the specified 
key and digest algorithm. Note, the digest algorithm is being specified when the context is allocated with 
the CertMgrSignatureInitContext function. The process of verification or generation of a signature over an 
arbitrarily long message, follows a sequence laid out below: 


e allocate and initialize context 
e verify or generate (repeated n times) 


e release context. 


Sync (or) Async: 


This is a Synchronous API. 


Important Notes: 


e Note: n/a 


Parameters: 


context input/output - a context record address previously allocated with a call to CertMgrSignature- 
InitContext. 


keyDescriptor input - a key descriptor record. 
message input - a message specification record (either a fragment or the whole message). 


final input - a boolean, if true, signals that the current invocation contains the last message part in its 
message buffer. 


signature input - a signature descriptor record. 


Returns: 


Return Type (CertMgrResult) 
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e OPERATION_SUCCESS - the signature is correct for the specified message. 
e ERR CMSIG UNSUPPORTED HASH TYP - the specified algorithm is not supported. 


Prospective Clients: 


Certificate manager foundation API. 


Example of how this function would be called: 


CertMgrResult result; 


void *context; 
int iteration; 


CertMgrFilBuff x«msgOnFile 
CertMgrMemBuff  *message; 


some initialization etc. 


result = CertMgrSignaturelnitContext (CERTMGR HASH MD2, &context ); 


if (result == OPERATION SUCCESS) 
{ 
while( allDone == FALSE && moreBuffs == TRUE ) 
{ 
moreBuffs = getNextMessageBuffer (msgOnFile, message, ...) 


CertMgrSignatureVerify (context, keyDescriptor, message, FALSE, signature) 
) 
CertMgrSignatureVerify(context, keyDescriptor, message, TRUE, signature) 
CertMgrSignatureReleaseContext (context) 
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5.9 CertMgrStore.h File Reference 


5.9.1 Detailed Description 


This file specifies the storage services supplied by the certificate store plug-in component for the certificate 
manager. 


#include "CertMgr.h" 


Defines 


e #define ERR CMSTORE IS FULL ( (INT32)(CERTSTORE_START_ERRCODE - 1) ) 


function return error code indicating insufficient storage space available 


Functions 


e CertMgrResult CertMgrStorelnitialize (CertMgrStorageld storeld, char xinitParas) 


This function is used to initialize the store. 


CertMgrResult CertMgrStoreStoreCertificate (CertMgrMemBuff «certificate, CertMgrCertld 
*certificateld) 


This function is used to store one certificate to this store. 


CertMgrResult CertMgrStoreRemoveCertificate (CertMgrCertld «certificateld) 


This function is used to remove one certificate from this store. 


CertMgrResult CertMgrStoreEnableCertificate (CertMgrCertld xcertificateld) 


This function is used to enable one certificate from this store. 


CertMgrResult CertMgrStoreDisableCertificate (CertMgrCertld xcertificateld) 


This function is used to disable one certificate from this store. 


CertMgrResult CertMgrStoreRemoveAllUserCertificates (void) 


This function is used to remove all certificates from this store. 


CertMgrResult  CertMgrStoreRetrieveCertificate (CertMgrCtx context, CertMgrMemBuff 
«certificate, CertMgrCertld *certificateld) 


This function is used to retrieve one or more certificates. 


CertMgrResult CertMgrStoreRetrieveCertificateStatus (CertMgrCertld «certificateld, CertMgrCert- 
Status xstatus) 


This function is used to to get the status (enabled/disabled) of the specified certificate. 


5.9.2 Define Documentation 
5.9.2.1 #define ERR CMSTORE IS FULL ((INT32(CERTSTORE_START_ERRCODE - 1) ) 


function return error code indicating insufficient storage space available 
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5.9.3 Function Documentation 
5.9.3.1 CertMgrResult CertMgrStoreDisableCertificate (CertMgrCertld x certificateld) 
This function is used to disable one certificate from this store. 
Sync (or) Async: 
This is a Synchronous API. 


Important Notes: 
e Note: n/a 


Parameters: 


certificateld input - specifies the certificate to be disabled. 


Returns: 
Return Type (CertMgrResult) 
e OPERATION_SUCCESS - certificate successfully disabled 
e Otherwise return one appropriate error 
Prospective Clients: 


Certificate manager foundation API. 


5.9.3.2 CertMgrResult CertMgrStoreEnableCertificate (CertMgrCertld x certificateId) 
This function is used to enable one certificate from this store. 


Sync (or) Async: 


This is a Synchronous API. 


Important Notes: 
e Note: n/a 


Parameters: 


certificateld input - specifies the certificate to be enabled. 


Returns: 
Return Type (CertMgrResult) 
e OPERATION_SUCCESS - certificate successfully enabled 


e Otherwise return one appropriate error 


Prospective Clients: 


Certificate manager foundation API. 
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5.9.3.3 CertMgrResult CertMgrStorelnitialize (CertMgrStorageld storeld, char x initParas) 


This function is used to initialize the store. 


Sync (or) Async: 


This is a Synchronous API. 


Important Notes: 


e Note: n/a 


Parameters: 
storeld input - tells the store what id it has. 


initParas input - some initialization string needed by the store. 


Returns: 


Return Type (CertMgrResult) 


e OPERATION_SUCCESS - intialization successful 


e Otherwise return one appropriate error 


Prospective Clients: 


Certificate manager foundation API. 


5.9.3.4 CertMgrResult CertMgrStoreRemoveAllUserCertificates (void) 


This function is used to remove all certificates from this store. 


Sync (or) Async: 


This is a Synchronous API. 


Important Notes: 


e Note: n/a 


Returns: 


Return Type (CertMgrResult) 


e OPERATION_SUCCESS - all certificates successfully removed 


e Otherwise return one appropriate error 


Prospective Clients: 


Certificate manager foundation API. 
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5.9.3.5 CertMgrResult CertMgrStoreRemoveCertificate (CertMgrCertld x certificateld) 
This function is used to remove one certificate from this store. 


Sync (or) Async: 


This is a Synchronous API. 


Important Notes: 


e Note: n/a 


Parameters: 


certificateld input - specifies the certificate to be removed. 


Returns: 
Return Type (CertMgrResult) 
e OPERATION_SUCCESS - certificate successfully removed 


e Otherwise return one appropriate error 


Prospective Clients: 


Certificate manager foundation API. 


5.9.3.6 CertMgrResult CertMgrStoreRetrieveCertificate (CertMgrCtx « context, 
CertMgrMemBuff x certificate, CertMgrCertld x certificateld) 


This function is used to retrieve one or more certificates. 


Sync (or) Async: 


This is a Synchronous API. 


Important Notes: 


e Note: The context is used to keep track of the retrieval operation over successive calls 
e The context must be initialized to zero during the first call of this function. 


e Additionally, if the retrieval is to be by field, the field descriptor and the retrieveByField flag 
must be set appropriately. 


Parameters: 


context input/output - the address of a context record. 
certificate output - specifies the certificate memory buffer retrieved. 


certificateld output - specifies the certificate Id retrieved. 


Returns: 
Return Type (CertMgrResult) 
e OPERATION_SUCCESS - certificate successfully retrieved 


e Otherwise return one appropriate error 
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Prospective Clients: 


Certificate manager foundation API. 


Example of how this function would be called: 


CertMgrCtx xcontext; 


CertMgrMemBuff messageBuffer, 
CertMgrCertId certificateld 
CertMgrResult result = RESULT_CODE_SUCCESS; 


. initialize context, certificate buffer etc. 
while( (result == RESULT CODE SUCCESS) && (notFound == TRUE) ) 
{ 


result = CertMgrStoreRetrieveCertificate(context, &messageBuffer, &certificateId) 


5.9.3.7 CertMgrResult CertMgrStoreRetrieveCertificateStatus (CertMgrCertld x certificateld, 
CertMgrCertStatus + status) 


This function is used to to get the status (enabled/disabled) of the specified certificate. 


Sync (or) Async: 


This is a Synchronous API. 


Important Notes: 


e Note: n/a 


Parameters: 


certificateld input - specifies the certificate to be retrieved. 


status output - specifies the status (enabled/disabled) of the certificate. 


Returns: 
Return Type (CertMgrResult) 
e OPERATION_SUCCESS - certificate status successfully retrieved 


e Otherwise return one appropriate error 


Prospective Clients: 


Certificate manager foundation API. 


5.9.3.8 CertMgrResult CertMgrStoreStoreCertificate (CertMgrMemBuff x certificate, 
CertMgrCertld x certificateId) 


This function is used to store one certificate to this store. 
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Sync (or) Async: 
This is a Synchronous API. 


Important Notes: 


e Note: n/a 


Parameters: 


certificate input - specifies the certificate (memory buffer) to be stored. 


certificateld input/output - the certificate id of the certificate to be stored. 


Returns: 
Return Type (CertMgrResult) 
e OPERATION_SUCCESS - certificate successfully stored 
e ERR_CMSTORE_DUP_CERTIFICATE - certificate already exists in the store 
e ERR_CMSTORE_IS_FULL - no space left in store 
e ERR CMSTORE READ ONLY - the store is a "read only" type 


e Otherwise return one appropriate error 


Prospective Clients: 


Certificate manager foundation API. 
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